SuperAPI AI Directory

dym-arex-skill-contributor-phat-trien-cli

Coding & development

View repository

Updated 10-18 01:21

About this skill

Skill: dym-arex-skill-contributor-phat-trien-cli — Contributor: modify the DisCo CLI itself

Why use it: You clone AREX-Skill to change the tool, not to use it. What it produces: cli/dist/ built, one disco command linked from the checkout, and a gate tree that ran green.

This track is independent of 01–08. No need to install a release build first.


1. Code map (this is where it is easiest to get lost)

AREX-Skill/
├── cli/                                    ← package npm @arex-skill/disco
│   ├── package.json                        ← MANIFEST DUY NHẤT của cả repo
│   ├── npm-shrinkwrap.json                 ← dependency được ghim
│   ├── vitest.config.ts                    ← root test trỏ về packages/coding-agent
│   ├── tsconfig.build.json / tsconfig.examples.json
│   ├── AGENTS.md                           ← luật bảo trì provenance/release
│   ├── docs/                               ← 30+ trang tài liệu CLI
│   ├── scripts/                            ← upstream-provenance · verify-package · copy-assets
│   └── packages/coding-agent/
│       ├── UPSTREAM_MANIFEST.json          ← kiểm kê provenance
│       ├── src/
│       │   ├── cli.ts                      ← entry process (bin → dist/cli.js)
│       │   ├── main.ts                     ← điều phối, 33KB
│       │   ├── config.ts                   ← APP_NAME · CONFIG_DIR_NAME · đường dẫn agent dir
│       │   ├── package-manager-cli.ts      ← install/remove/update/list/config
│       │   ├── cli/args.ts                 ← PARSER CỜ + printHelp()
│       │   ├── cli/repo-skills.ts          ← subcommand repo-skills
│       │   ├── core/repo-skills-library-manager.ts  ← clone/adopt/update/drift
│       │   ├── core/slash-commands.ts      ← 24 lệnh chat built-in
│       │   ├── modes/print-mode.ts         ← -p / --mode json, exit code
│       │   ├── modes/interactive/          ← TUI (interactive-mode.ts ~207KB)
│       │   └── disco/skills/               ← 17 skill bundled (15 meta + 1 operating + 1 shared)
│       └── test/                           ← ~60 file test vitest
├── skills/repositories/                    ← thư viện runtime 1000 skill + router
├── docs/                                   ← tài liệu cấp repo (song ngữ EN/zh)
├── examples/                               ← export session HTML + starter TOML
└── scripts/                                ← installer + build-from-source-link.sh

There is no manifest besides cli/package.json — the repo is not a monorepo with workspaces.

2. Dev loop

cd cli
npm ci --ignore-scripts        # dùng npm-shrinkwrap.json đã ghim
npm run typecheck              # tsc --noEmit -p tsconfig.build.json
npm test                       # vitest --run + node --test scripts/upstream-provenance.test.mjs
npm run build                  # clean + tsc + copy-assets + chmod +x dist/cli.js dist/rpc-entry.js

Run a single test file:

cd cli
npx vitest --run packages/coding-agent/test/disco-mode-skills.test.ts

Tests run with DISCO_OFFLINE=1, PI_OFFLINE=1, fileParallelism: false, timeout 30s, reporter dot (vitest.config.ts). No parallelization — don't be surprised when it is slow.

Link the dev build as a global disco command:

cd ..
bash scripts/build-from-source-link.sh

3. Full gate before publishing

cd cli
npm run prepublishOnly

It runs 7 tasks sequentially, stopping wherever it breaks:

verify:provenance → typecheck → test → test:examples → verify:rpiv-todo-contract → build → verify:package
Script Real command What it guards
verify:provenance node scripts/upstream-provenance.mjs --check UPSTREAM_MANIFEST.json matches files on disk. Local-only, no Pi checkout needed
typecheck tsc --noEmit -p tsconfig.build.json Types
test vitest --run + node --test scripts/upstream-provenance.test.mjs Behavior
test:examples tsc --noEmit -p tsconfig.examples.json Examples in examples/ still compile
verify:rpiv-todo-contract node scripts/verify-rpiv-todo-contract.mjs RPIV TODO contract
build as above Output to dist/
verify:package node scripts/verify-package.mjs Audit exactly which files are packaged

Try packaging:

cd cli
npm publish --dry-run --ignore-scripts

4. Provenance — the most fragile part

Inventory scope: packages/coding-agent/src, packages/coding-agent/test, docs, examples.

cd cli

# Sau khi CỐ Ý sửa file đã có trong 4 thư mục trên:
npm run refresh:provenance

# Khi THÊM file mới do DisCo sở hữu — phải duyệt tường minh từng file:
npm run refresh:provenance -- --add-local docs/dynamic-workflows.md

Rules (from cli/AGENTS.md):

  • Refresh must not silently swallow foreign files, accept missing declared files, or change upstream hash/mapping. Read the manifest diff after refreshing.
  • The full upstream workflow is only used when the Pi baseline actually changes:
    node scripts/upstream-provenance.mjs --write --upstream-root /path/to/pi
    
    Needs a clean Pi checkout, pinned to the correct repo/tag/commit. Do not clean/modify the Pi checkout externally just so a release can cli.
  • scripts/build-from-source-link.sh is smoke build/link, not a release gate.
  • Git worktree does not need to be clean to release npm, but you should commit/tag the reviewed state so it can be traced back to the correct revision.

5. Modify bundled skills

Single source of truth: cli/packages/coding-agent/src/disco/skills/.

When modifying:

  • Declare clearly the expected input and output;
  • Ask for user confirmation at expensive or destructive points, unless the user has already authorized it;
  • Keep environment changes isolated;
  • Separate runtime-generated content from tests and reports;
  • Decouple installing the meta-skill from deploying the graph it generates;
  • The repo graph goes through a specialized import path ~/.disco/agent/skills/repositories/repo-skills/ + rebuild sibling routers — do not push routing metadata through the general graph importer;
  • Update cli/packages/coding-agent/src/disco/skills/README.md when the name/path/default/boundary changes;
  • Modify the generator and the template at the same time. Router behavior rendered by update_repo_skills_router.mjs is rendered by must not be changed only in the committed Markdown file.

The bundled test skill sits right next to it: cli/packages/coding-agent/src/disco/skills/*.test.ts (9 files, e.g. export_repo_skills_to_agent.test.ts, skill-role-contracts.test.ts).

6. What to test when touching discovery/routing

According to CONTRIBUTING.md, changes to the skill discovery & routing path must prove:

  • hidden skills are managed registered but do not leak into the initial prompt;
  • the live router overrides the bundled fallback;
  • skills of a project that is not trusted are not loaded;
  • skills from installed packages remain usable.

7. Installer release assets

The installer at the repo root is published as a GitHub Release asset, not included in the npm tarball:

python3 scripts/prepare-disco-release-assets.py

Write out dist/disco-release-assets/: install-disco.sh, install-disco.ps1, SHA256SUMS, release-metadata.json. Attach the 2 installer files + SHA256SUMS to the corresponding GitHub Release, verify the URL releases/latest/download is stable before updating public docs. The standard npm release helper prepares these files but never uploads or creates a GitHub Release on its own.

8. Pitfalls

  • The repo has no CI. There is no .github/workflows/ — every gate must be run manually. npm run prepublishOnly is the closest thing to "CI".
  • Do not manually edit dist/ or the runtime assets of the standalone binary as if they were source.
  • Bilingual docs. The root README, installation, architecture, disco-meta-skills, refreshing-repo-skills, CONTRIBUTING, and skills/README are EN/zh pairs — changing one side requires changing the other in the same change.
  • repository-catalog.md weighs 673KB — a shared data page covering 1000 roots and 2209 memberships. When changing the catalog, keep the counts, grouping, paths, and summary section in the Chinese README in sync.
  • Node must be >= 22.19.0. Lower versions may npm ci but break at runtime.

9. Drift bugs found (read the code, not the README)

docs/disco-workflows.md and cli/docs/packages.md (section Mode Targeting) both document:

disco install <source> --for creator|researcher|both|default

The flag --for does not exist in the parser. package-manager-cli.ts has no branch that catches --for; it falls into invalidOption and the command prints:

Unknown option --for for "install".

then process.exitCode = 1. The command's official usage string is disco install <source> [-l] [--approve|--no-approve]. This is a case of docs ahead of code (or code having fallen behind) — a worthwhile PR.

Next step

10-contributor-dong-gop-skill.md if you contribute skill rather than CLI code.