@skillit/cli 0.4.0

package/dist/program-loader.js

@@ -0,0 +1,90 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { Command } from 'commander';
+const LOAD_ERROR = 'Could not load a commander program; pass --program <file#export>';
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Resolves a candidate export into a commander {@link Command}.
+ *
+ * Accepts either a `Command` instance directly or a zero-argument factory
+ * function that returns one. Returns `undefined` for anything else.
+ */
+async function resolveCommand(candidate) {
+    if (candidate instanceof Command) {
+        return candidate;
+    }
+    if (typeof candidate === 'function' &&
+        candidate.length === 0) {
+        const result = await candidate();
+        if (result instanceof Command) {
+            return result;
+        }
+    }
+    return undefined;
+}
+async function importModule(absPath) {
+    return (await import(pathToFileURL(absPath).href));
+}
+/**
+ * Loads a commander program for refinement.
+ *
+ * When `opts.program` is provided as `file#export`, the file is resolved
+ * against `cwd`, imported, and the named export is used (a `Command` or a
+ * zero-arg factory). Otherwise the program is auto-discovered from the
+ * consumer's `package.json` `bin` entry, probing the exports `buildProgram`,
+ * `createProgram`, `program`, then `default`.
+ *
+ * @throws Error advising `--program <file#export>` when no program can be loaded.
+ */
+export async function loadProgram(opts) {
+    if (opts.program !== undefined) {
+        const [file, exportName] = opts.program.split('#');
+        if (!file || !exportName) {
+            throw new Error(LOAD_ERROR);
+        }
+        const absPath = path.resolve(opts.cwd, file);
+        let mod;
+        try {
+            mod = await importModule(absPath);
+        }
+        catch (cause) {
+            throw new Error(`Could not import '${absPath}'; pass --program <file#export>: ${messageOf(cause)}`, { cause });
+        }
+        const command = await resolveCommand(mod[exportName]);
+        if (!command) {
+            throw new Error(`Export '${exportName}' from '${absPath}' is not a commander Command or factory; pass --program <file#export>`);
+        }
+        return command;
+    }
+    const pkgPath = path.join(opts.cwd, 'package.json');
+    let bin;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        bin = typeof pkg.bin === 'string' ? pkg.bin : Object.values(pkg.bin ?? {})[0];
+    }
+    catch {
+        throw new Error(LOAD_ERROR);
+    }
+    if (!bin) {
+        throw new Error(LOAD_ERROR);
+    }
+    const absBin = path.resolve(opts.cwd, bin);
+    let mod;
+    try {
+        mod = await importModule(absBin);
+    }
+    catch {
+        throw new Error(LOAD_ERROR);
+    }
+    for (const exportName of ['buildProgram', 'createProgram', 'program', 'default']) {
+        const command = await resolveCommand(mod[exportName]);
+        if (command) {
+            return command;
+        }
+    }
+    throw new Error(LOAD_ERROR);
+}
+//# sourceMappingURL=program-loader.js.map

package/dist/program-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"program-loader.js","sourceRoot":"","sources":["../src/program-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,MAAM,UAAU,GAAG,kEAAkE,CAAC;AAEtF,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,cAAc,CAAC,SAAkB;IAC9C,IAAI,SAAS,YAAY,OAAO,EAAE,CAAC;QACjC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IACE,OAAO,SAAS,KAAK,UAAU;QAC9B,SAA6C,CAAC,MAAM,KAAK,CAAC,EAC3D,CAAC;QACD,MAAM,MAAM,GAAG,MAAO,SAA2B,EAAE,CAAC;QACpD,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;YAC9B,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,OAAe;IACzC,OAAO,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAA4B,CAAC;AAChF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAwB;IACxD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACnD,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC;QAC9B,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC7C,IAAI,GAA4B,CAAC;QACjC,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC;QACpC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,qBAAqB,OAAO,oCAAoC,SAAS,CAAC,KAAK,CAAC,EAAE,EAClF,EAAE,KAAK,EAAE,CACV,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;QACtD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,WAAW,UAAU,WAAW,OAAO,uEAAuE,CAC/G,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;IACpD,IAAI,GAAuB,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAEnD,CAAC;QACF,GAAG,GAAG,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IACD,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC3C,IAAI,GAA4B,CAAC;IACjC,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK,MAAM,UAAU,IAAI,CAAC,cAAc,EAAE,eAAe,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;QACjF,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;QACtD,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC;AAC9B,CAAC"}

package/dist/refine-source.d.ts

@@ -0,0 +1,32 @@
+import { type AuditContext, type DraftedFix, type ExtractedSkill, type RefineSource } from '@skillit/core';
+import { Command } from 'commander';
+export interface CliRefineSourceOptions {
+    /** Commander program to introspect. */
+    program: Command;
+    /** Glob for the consumer's TypeScript source files to read/edit. */
+    sourceGlob: string;
+    /** Working directory (reserved for future relative-path resolution). */
+    cwd: string;
+}
+/**
+ * {@link RefineSource} for `@skillit/cli` consumers.
+ *
+ * Extracts a skill from a commander program, returns the bundled CLI
+ * documentation conventions as guidance, and writes routing tags as JSDoc
+ * onto the correlated `<Command>Options` interface.
+ */
+export declare class CliRefineSource implements RefineSource {
+    private readonly opts;
+    constructor(opts: CliRefineSourceOptions);
+    /** Maps a command name to its options-interface name, e.g. `add-remote` → `AddRemoteOptions`, `db:migrate` → `DbMigrateOptions`. */
+    private interfaceName;
+    extract(): Promise<ExtractedSkill>;
+    guidance(): string;
+    auditContext(_skill: ExtractedSkill): AuditContext;
+    applyFixes(fixes: readonly DraftedFix[]): Promise<void>;
+    /** Reads tags for an interface across every globbed source file, first match wins. */
+    private readTagsAcross;
+    private readSources;
+    private findInterfaceFile;
+}
+//# sourceMappingURL=refine-source.d.ts.map

package/dist/refine-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refine-source.d.ts","sourceRoot":"","sources":["../src/refine-source.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,UAAU,EAEf,KAAK,cAAc,EACnB,KAAK,YAAY,EAElB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOpC,MAAM,WAAW,sBAAsB;IACrC,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,YAAW,YAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,sBAAsB,EAAI;IAE7D,oIAAoI;IACpI,OAAO,CAAC,aAAa;IASf,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,CAkDvC;IAED,QAAQ,IAAI,MAAM,CAKjB;IAED,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,CAEjD;IAEK,UAAU,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB5D;IAED,sFAAsF;IACtF,OAAO,CAAC,cAAc;YAiBR,WAAW;IAUzB,OAAO,CAAC,iBAAiB;CAQ1B"}

package/dist/refine-source.js

@@ -0,0 +1,147 @@
+import { readFileSync } from 'node:fs';
+import { glob, readFile, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { upsertJsDocTag } from '@skillit/core';
+import { extractCliSkill } from './extract.js';
+import { introspectCommander } from './introspect-commander.js';
+import { readOptionsTags } from './options-jsdoc.js';
+const EXCLUDED_DIRS = new Set(['node_modules', 'dist', 'build', '.git', 'coverage', '.cache']);
+/**
+ * {@link RefineSource} for `@skillit/cli` consumers.
+ *
+ * Extracts a skill from a commander program, returns the bundled CLI
+ * documentation conventions as guidance, and writes routing tags as JSDoc
+ * onto the correlated `<Command>Options` interface.
+ */
+export class CliRefineSource {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Maps a command name to its options-interface name, e.g. `add-remote` → `AddRemoteOptions`, `db:migrate` → `DbMigrateOptions`. */
+    interfaceName(command) {
+        const pascal = command
+            .split(/[-_:.\s]+/)
+            .filter((part) => part.length > 0)
+            .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+            .join('');
+        return `${pascal}Options`;
+    }
+    async extract() {
+        const surfaces = introspectCommander(this.opts.program);
+        const sources = await this.readSources();
+        const configSurfaces = [];
+        for (const surface of surfaces) {
+            const iface = this.interfaceName(surface.name);
+            const tags = this.readTagsAcross(iface, sources);
+            // Key the correlation-input surface by the COMMAND name (not the
+            // interface name) so `extractCliSkill`'s `<command>`/`<command>options`
+            // lookup matches colon-namespaced commands (e.g. `db:migrate`). Mark it
+            // `cli` so it is correlated onto the command surface rather than emitted
+            // as a separate 0-option `config` surface.
+            const configSurface = {
+                name: surface.name,
+                description: '',
+                sourceType: 'cli',
+                options: []
+            };
+            let hasContent = false;
+            if (tags.useWhen !== undefined) {
+                configSurface.useWhen = [tags.useWhen];
+                hasContent = true;
+            }
+            if (tags.avoidWhen !== undefined) {
+                configSurface.avoidWhen = [tags.avoidWhen];
+                hasContent = true;
+            }
+            if (tags.pitfalls !== undefined) {
+                configSurface.pitfalls = [tags.pitfalls];
+                hasContent = true;
+            }
+            if (tags.remarks !== undefined) {
+                configSurface.remarks = tags.remarks;
+                hasContent = true;
+            }
+            if (tags.example !== undefined) {
+                configSurface.usage = tags.example;
+                hasContent = true;
+            }
+            // Only emit a surface when at least one consumed field is populated;
+            // a truly-empty read contributes nothing but noise.
+            if (hasContent) {
+                configSurfaces.push(configSurface);
+            }
+        }
+        return extractCliSkill({ program: this.opts.program, configSurfaces });
+    }
+    guidance() {
+        const skillPath = fileURLToPath(new URL('../skills/skillit-cli-docs/SKILL.md', import.meta.url));
+        return readFileSync(skillPath, 'utf8');
+    }
+    auditContext(_skill) {
+        return {};
+    }
+    async applyFixes(fixes) {
+        const sources = await this.readSources();
+        for (const fix of fixes) {
+            const iface = this.interfaceName(fix.toolName);
+            const file = this.findInterfaceFile(iface, sources);
+            if (!file) {
+                process.stderr.write(`[skillit] no ${iface} interface for command '${fix.toolName}'; skipped ${fix.tag}\n`);
+                continue;
+            }
+            const src = sources.get(file);
+            const next = upsertJsDocTag(src, iface, fix.tag, fix.value);
+            if (next !== src) {
+                await writeFile(file, next, 'utf8');
+                // Keep the in-memory map current so subsequent fixes targeting the
+                // same file build on this edit instead of clobbering it.
+                sources.set(file, next);
+            }
+        }
+    }
+    /** Reads tags for an interface across every globbed source file, first match wins. */
+    readTagsAcross(iface, sources) {
+        for (const src of sources.values()) {
+            if (!fileDeclaresInterface(src, iface)) {
+                continue;
+            }
+            const tags = readOptionsTags(iface, src);
+            if (Object.keys(tags).length > 0) {
+                return tags;
+            }
+        }
+        return {};
+    }
+    /** Globs the source files once and returns a file → contents map. */
+    async readSources() {
+        const sources = new Map();
+        for await (const file of glob(this.opts.sourceGlob, {
+            exclude: (f) => f.endsWith('.d.ts') || f.split(/[\\/]/).some((seg) => EXCLUDED_DIRS.has(seg))
+        })) {
+            sources.set(file, await readFile(file, 'utf8'));
+        }
+        return sources;
+    }
+    findInterfaceFile(iface, sources) {
+        for (const [file, contents] of sources) {
+            if (fileDeclaresInterface(contents, iface)) {
+                return file;
+            }
+        }
+        return undefined;
+    }
+}
+/**
+ * Returns whether `src` declares the interface named exactly `iface`.
+ *
+ * Matches on identifier boundaries so the probe for `GenOptions` does not
+ * spuriously match `interface GenOptionsExtra`. Shared by file-selection
+ * (`findInterfaceFile`) and tag-reading (`readTagsAcross`) so both agree on
+ * what counts as the interface.
+ */
+function fileDeclaresInterface(src, iface) {
+    const escaped = iface.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return src.match(new RegExp(String.raw `\binterface\s+${escaped}\b`)) !== null;
+}
+//# sourceMappingURL=refine-source.js.map

package/dist/refine-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refine-source.js","sourceRoot":"","sources":["../src/refine-source.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@skillit/cli",
+  "version": "0.4.0",
+  "description": "Extract CLI command structure from commander/yargs for AI agent skill generation",
+  "keywords": [
+    "agent-skills",
+    "ai",
+    "cli",
+    "commander",
+    "documentation",
+    "introspection",
+    "skill-generation",
+    "skill-md",
+    "skillit",
+    "typescript",
+    "yargs"
+  ],
+  "license": "MIT",
+  "author": "Pradeep Mouli",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pradeepmouli/skillit.git",
+    "directory": "packages/cli"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/pradeepmouli"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "skills"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@skillit/core": "1.5.0"
+  },
+  "devDependencies": {
+    "commander": "^14.0.3"
+  },
+  "peerDependencies": {
+    "commander": ">=12.0.0"
+  },
+  "peerDependenciesMeta": {
+    "commander": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json",
+    "type-check": "tsgo --noEmit"
+  }
+}

package/skills/skillit-cli-docs/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: skillit-cli-docs
+description: 'CLI documentation conventions for generated skills. Use when improving Commander descriptions, help text, positional argument docs, and config-surface correlation.'
+version: 0.3.13
+toSkills:
+  managed: bundled-guidance
+---
+
+# CLI Documentation Conventions
+
+Use this skill when documenting command-line programs for `@skillit/cli`.
+
+## Focus Areas
+
+- `.description()` text on commands and subcommands
+- `.option()` and `--help` descriptions for every flag
+- `.argument()` descriptions for positional inputs
+- `.usage()` strings and example help text
+- Environment-variable documentation and config-surface JSDoc correlation
+
+## Fix Patterns
+
+- Describe command intent in one sentence, not just the verb
+- Explain what each option changes in behavior
+- Document positional arguments with expected format or values
+- Mention env vars explicitly when an option supports them