@open-agent-toolkit/cli 0.3.28 → 0.3.30

package/dist/commands/docs/literals/evidence.d.ts

@@ -0,0 +1,39 @@
+export declare class LiteralInputError extends Error {
+}
+export interface LiteralOptions {
+    cwd: string;
+    targetDir?: string;
+    page: string[];
+    sourceRoot: string[];
+    sourceExclude: string[];
+}
+interface Candidate {
+    path: string;
+    line: number;
+    literal: string;
+    normalized: string;
+    status: 'found' | 'not-found';
+    source?: {
+        path: string;
+        line: number;
+    };
+}
+export interface LiteralResult {
+    status: 'ok' | 'not-applicable';
+    reason?: string;
+    scope: {
+        contentRoot: string;
+        pages: string[];
+        sourceRoots: string[];
+        sourceExcludes: string[];
+    };
+    searched: string[];
+    skipped: {
+        path: string;
+        reason: 'symlink' | 'binary' | 'non-utf8' | 'non-regular';
+    }[];
+    literals: Candidate[];
+}
+export declare function collectLiteralEvidence(options: LiteralOptions): Promise<LiteralResult>;
+export {};
+//# sourceMappingURL=evidence.d.ts.map

package/dist/commands/docs/literals/evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/literals/evidence.ts"],"names":[],"mappings":"AAgBA,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAE/C,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AACD,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,GAAG,WAAW,CAAC;IAC9B,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC;AACD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,IAAI,GAAG,gBAAgB,CAAC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE;QACL,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,cAAc,EAAE,MAAM,EAAE,CAAC;KAC1B,CAAC;IACF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,CAAC;KAC3D,EAAE,CAAC;IACJ,QAAQ,EAAE,SAAS,EAAE,CAAC;CACvB;AAkDD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CA6MxB"}

package/dist/commands/docs/literals/evidence.js

@@ -0,0 +1,205 @@
+import { lstat, readFile, readdir, realpath, stat } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import { containedFile, inside, posix, resolveCheckTarget, } from '../../docs/check/files.js';
+import { parsePage } from '../../docs/check/markdown.js';
+import { createExclusionMatcher, isExcludedPath, } from '../../docs/shared/exclusions.js';
+import { decodeHTMLStrict } from 'entities';
+export class LiteralInputError extends Error {
+}
+function inputPath(value, label, pattern = false) {
+    const path = value.trim().replace(/^\.\//, '');
+    const parts = path.replace(/\/$/, '').split('/');
+    if (!path ||
+        path.startsWith('/') ||
+        /^[A-Za-z]:/.test(path) ||
+        path.includes('\\') ||
+        [...path].some((c) => c.charCodeAt(0) < 32) ||
+        parts.some((p) => !p || p === '.' || p === '..') ||
+        (!pattern && path.includes('*')))
+        throw new LiteralInputError(`${label} must be a non-empty relative POSIX ${pattern ? 'pattern' : 'path'} without parent segments.`);
+    return pattern ? path : path.replace(/\/$/, '');
+}
+const unique = (values) => [...new Set(values)].sort();
+async function selected(label, operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (['ENOENT', 'ENOTDIR', 'EACCES', 'EPERM', 'ELOOP', 'EISDIR'].includes(error.code ?? ''))
+            throw new LiteralInputError(`Cannot read ${label}; check that it exists and is readable.`);
+        throw error;
+    }
+}
+function text(bytes) {
+    if (bytes.includes(0))
+        return { reason: 'binary' };
+    try {
+        return { value: new TextDecoder('utf-8', { fatal: true }).decode(bytes) };
+    }
+    catch {
+        return { reason: 'non-utf8' };
+    }
+}
+export async function collectLiteralEvidence(options) {
+    const target = await selected('documentation target/config', async () => {
+        try {
+            return await resolveCheckTarget(options.cwd, options.targetDir);
+        }
+        catch (error) {
+            if (!error.code)
+                throw new LiteralInputError('Cannot resolve documentation target/config; check .oat/config.json, documentation.root, documentation.ia and --target-dir.');
+            throw error;
+        }
+    });
+    const result = {
+        status: 'not-applicable',
+        scope: {
+            contentRoot: posix(relative(target.repoRoot, target.contentRoot)) || '.',
+            pages: [],
+            sourceRoots: [],
+            sourceExcludes: [],
+        },
+        searched: [],
+        skipped: [],
+        literals: [],
+    };
+    // Config is only the extraction gate. The skill separately reconciles authored acceptance.
+    if (target.documentation.ia?.verification !== 'triad') {
+        result.reason =
+            'The matching documentation IA mirror does not declare verification: triad.';
+        return result;
+    }
+    if (!inside(target.repoRoot, target.contentRoot))
+        throw new LiteralInputError('Docs content root must be inside the repository.');
+    if (!options.page.length || !options.sourceRoot.length)
+        throw new LiteralInputError('Provide at least one --page and one narrow --source-root.');
+    const pages = unique(options.page.map((p) => inputPath(p, '--page')));
+    const roots = unique(options.sourceRoot.map((p) => inputPath(p, '--source-root')));
+    const excludes = unique(options.sourceExclude.map((p) => inputPath(p, '--source-exclude', true)));
+    result.scope = {
+        contentRoot: result.scope.contentRoot,
+        pages,
+        sourceRoots: roots,
+        sourceExcludes: excludes,
+    };
+    const matcher = createExclusionMatcher(excludes);
+    const sources = new Set();
+    const skipped = new Map();
+    // Inspect each component so an explicitly selected nested alias cannot bypass traversal policy.
+    const symlinkComponent = async (root, path) => {
+        const parts = path.split('/');
+        for (let i = 1; i <= parts.length; i++) {
+            if ((await lstat(join(root, ...parts.slice(0, i)))).isSymbolicLink())
+                return true;
+        }
+        return false;
+    };
+    const walk = async (path) => {
+        const absolute = join(target.repoRoot, path);
+        const info = await selected(`source ${path}`, () => lstat(absolute));
+        if (info.isSymbolicLink()) {
+            skipped.set(path, 'symlink');
+            return;
+        }
+        if (isExcludedPath(matcher, path, info.isDirectory()))
+            return;
+        if (info.isDirectory()) {
+            const entries = await selected(`source directory ${path}`, () => readdir(absolute));
+            for (const name of entries.sort())
+                await walk(`${path}/${name}`);
+        }
+        else if (info.isFile())
+            sources.add(path);
+        else
+            skipped.set(path, 'non-regular');
+    };
+    for (const path of roots) {
+        await selected(`source root ${path}`, async () => {
+            const absolute = resolve(target.repoRoot, path);
+            if (!inside(target.repoRoot, absolute) || absolute === target.repoRoot)
+                throw new LiteralInputError('Source roots must be narrow directories inside the repository, never the repository root.');
+            if (await symlinkComponent(target.repoRoot, path)) {
+                // An external alias is invalid input, even though it will never be read.
+                if (!inside(target.repoRoot, await realpath(absolute)))
+                    throw new LiteralInputError(`Source root ${path} resolves outside the repository.`);
+                skipped.set(path, 'symlink');
+                return;
+            }
+            if (!inside(target.repoRoot, await realpath(absolute)) ||
+                !(await stat(absolute)).isDirectory())
+                throw new LiteralInputError(`Source root ${path} must be a contained directory.`);
+            const canonical = posix(relative(await realpath(target.repoRoot), await realpath(absolute)));
+            if (canonical !== path)
+                throw new LiteralInputError(`Source root ${path} must use its canonical repo-relative spelling: ${canonical}.`);
+            await walk(path);
+        });
+    }
+    const sourceLines = [];
+    for (const path of [...sources].sort()) {
+        if (!(await containedFile(target.repoRoot, join(target.repoRoot, path))))
+            throw new LiteralInputError(`Source ${path} is no longer a contained file; rerun with stable inputs.`);
+        const decoded = text(await selected(`source ${path}`, () => readFile(join(target.repoRoot, path))));
+        if ('reason' in decoded)
+            skipped.set(path, decoded.reason);
+        else {
+            result.searched.push(path);
+            sourceLines.push({
+                path,
+                lines: decoded.value
+                    .split(/\r\n|\n|\r/)
+                    .map((line) => decodeHTMLStrict(line)),
+            });
+        }
+    }
+    if (!sourceLines.length)
+        throw new LiteralInputError(`No readable UTF-8 source files remain after exclusions; correct --source-root/--source-exclude. Skipped: ${[...skipped]
+            .sort()
+            .map(([path, reason]) => `${path} (${reason})`)
+            .join(', ') || 'none'}.`);
+    for (const path of pages) {
+        await selected(`page ${path}`, async () => {
+            const absolute = resolve(target.contentRoot, path);
+            if (!/\.mdx?$/.test(path) ||
+                isExcludedPath(target.matcher, path) ||
+                (await symlinkComponent(target.contentRoot, path)) ||
+                !(await containedFile(target.contentRoot, absolute)))
+                throw new LiteralInputError(`Page ${path} must be readable reader Markdown inside the content root, outside nonReaderPaths, with no symlink components below the content root.`);
+            const canonical = posix(relative(await realpath(target.contentRoot), await realpath(absolute)));
+            if (canonical !== path)
+                throw new LiteralInputError(`Page ${path} must use its canonical content-relative spelling: ${canonical}.`);
+            const decoded = text(await readFile(absolute));
+            if ('reason' in decoded)
+                throw new LiteralInputError(`Page ${path} must be UTF-8 Markdown text.`);
+            const page = parsePage(path, decoded.value);
+            if (page.frontmatterError)
+                throw new LiteralInputError(`Page ${path} has invalid YAML frontmatter.`);
+            for (const node of page.nodes) {
+                if (node.type !== 'inlineCode')
+                    continue;
+                const literal = node.value ?? '';
+                const normalized = decodeHTMLStrict(literal);
+                const candidate = {
+                    path,
+                    line: node.position?.start.line ?? 1,
+                    literal,
+                    normalized,
+                    status: 'not-found',
+                };
+                for (const source of sourceLines) {
+                    const index = source.lines.findIndex((line) => line.includes(normalized));
+                    if (index >= 0) {
+                        candidate.status = 'found';
+                        candidate.source = { path: source.path, line: index + 1 };
+                        break;
+                    }
+                }
+                result.literals.push(candidate);
+            }
+        });
+    }
+    result.status = 'ok';
+    result.skipped = [...skipped]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([path, reason]) => ({ path, reason }));
+    return result;
+}

package/dist/commands/docs/literals/literals.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createDocsLiteralsCommand(): Command;
+//# sourceMappingURL=literals.d.ts.map

package/dist/commands/docs/literals/literals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"literals.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/literals/literals.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC,wBAAgB,yBAAyB,IAAI,OAAO,CAmEnD"}

package/dist/commands/docs/literals/literals.js

@@ -0,0 +1,50 @@
+import { buildCommandContext } from '../../../app/command-context.js';
+import { readGlobalOptions } from '../../shared/shared.utils.js';
+import { Command } from 'commander';
+import { collectLiteralEvidence, LiteralInputError, } from './evidence.js';
+export function createDocsLiteralsCommand() {
+    const append = (value, previous = []) => previous.concat(value);
+    return new Command('literals')
+        .allowExcessArguments(false)
+        .description('Read-only triad inline-code occurrence candidates; found does not prove runtime behavior')
+        .option('--target-dir <dir>', 'Docs app root or literal Markdown content root')
+        .requiredOption('--page <path>', 'Content-relative Product/QA reader Markdown (repeat one value per flag)', append)
+        .requiredOption('--source-root <dir>', 'Narrow repo-relative implementation directory, never repo root (repeatable)', append)
+        .option('--source-exclude <pattern>', 'Repo-relative bounded POSIX exclusion: segment *, whole-segment **, trailing / directories (repeatable)', append, [])
+        .addHelpText('after', '\nMatching: one strict HTML entity decode per inline-code value and physical source line; case-sensitive substring. CommonMark may normalize multiline code spans. No whitespace/Unicode folding, JS escapes, interpolation or runtime evaluation. Sources are searched only within explicit roots; inspect searched/skipped evidence. Exit 0: completed (including not-found/not-applicable); 1: input/config; 2: runtime failure.')
+        .action(async (options, command) => {
+        const context = buildCommandContext(readGlobalOptions(command));
+        try {
+            const result = await collectLiteralEvidence({
+                ...options,
+                cwd: context.cwd,
+            });
+            process.exitCode = 0;
+            if (context.json)
+                context.logger.json(result);
+            else {
+                context.logger.info(result.status === 'not-applicable'
+                    ? `Not applicable: ${result.reason}`
+                    : `Literal occurrence candidates: ${result.literals.filter((c) => c.status === 'found').length} found, ${result.literals.filter((c) => c.status === 'not-found').length} not-found. These require canonical-source judgment.`);
+                context.logger.info(JSON.stringify({
+                    scope: result.scope,
+                    searched: result.searched,
+                    skipped: result.skipped,
+                    literals: result.literals,
+                }));
+            }
+        }
+        catch (error) {
+            const input = error instanceof LiteralInputError;
+            process.exitCode = input ? 1 : 2;
+            // Resolver/config diagnostics can carry local absolute paths; keep evidence relative.
+            const message = error.message
+                .replaceAll(`${context.cwd}/`, '')
+                .replaceAll(context.cwd, '.');
+            if (context.json)
+                context.logger.json({ status: 'error', message });
+            else
+                context.logger.error(message);
+        }
+    });
+}

package/dist/release/public-package-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public-package-contract.d.ts","sourceRoot":"","sources":["../../src/release/public-package-contract.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,KAAK,GAAG,cAAc,GAAG,iBAAiB,CAAC;IACjD,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,uBAAuB,EAAE,yBAAyB,EAAE,CAAC;IACrD,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,4BAA4B,EAAE,MAAM,EAAE,CAAC;IACvC,2BAA2B,EAAE,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAqMD,wBAAgB,yBAAyB,IAAI,qBAAqB,EAAE,CAenE;AAED,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,EAAE,CAIV;AAED,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,EAAE,CAIV;AAED,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,EAAE,CAMV;AAED,wBAAgB,6BAA6B,CAC3C,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACjD,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,EAAE,CAoBV;AAED,wBAAgB,oCAAoC,CAClD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,MAAM,EAAE,CAmBV;AAED,wBAAgB,qCAAqC,CACnD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,kBAAkB,EAAE,SAAS,MAAM,EAAE,EACrC,qBAAqB,EAAE,SAAS,MAAM,EAAE,GACvC,MAAM,EAAE,CA0BV"}
+{"version":3,"file":"public-package-contract.d.ts","sourceRoot":"","sources":["../../src/release/public-package-contract.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,KAAK,GAAG,cAAc,GAAG,iBAAiB,CAAC;IACjD,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,uBAAuB,EAAE,yBAAyB,EAAE,CAAC;IACrD,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,4BAA4B,EAAE,MAAM,EAAE,CAAC;IACvC,2BAA2B,EAAE,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AA+MD,wBAAgB,yBAAyB,IAAI,qBAAqB,EAAE,CAenE;AAED,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,EAAE,CAIV;AAED,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,EAAE,CAIV;AAED,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,EAAE,CAMV;AAED,wBAAgB,6BAA6B,CAC3C,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACjD,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,EAAE,CAoBV;AAED,wBAAgB,oCAAoC,CAClD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,MAAM,EAAE,CAmBV;AAED,wBAAgB,qCAAqC,CACnD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,kBAAkB,EAAE,SAAS,MAAM,EAAE,EACrC,qBAAqB,EAAE,SAAS,MAAM,EAAE,GACvC,MAAM,EAAE,CA0BV"}

package/dist/release/public-package-contract.js

@@ -76,6 +76,16 @@ const PUBLIC_PACKAGE_CONTRACTS = [
             'assets/templates/pjm-agents.md',
             'assets/templates/reference-agents.md',
             'assets/skills/explainer-kit/scripts/lib/package-coverage.mjs',
+            'assets/skills/authoring-docs/references/page-templates/product-feature.md',
+            'assets/skills/authoring-docs/references/page-templates/engineering-feature.md',
+            'assets/skills/authoring-docs/references/page-templates/qa-validation.md',
+            'assets/skills/authoring-docs/references/page-templates/screen-spec.md',
+            'assets/skills/authoring-docs/references/page-templates/alert-runbook.md',
+            'assets/skills/authoring-docs/references/page-templates/solution-record.md',
+            'assets/skills/authoring-docs/references/page-templates/command-reference.md',
+            'assets/skills/authoring-docs/references/page-templates/skill-command-guide.md',
+            'assets/skills/authoring-docs/references/page-templates/decisions-pointer.md',
+            'assets/skills/authoring-docs/references/page-templates/per-area-agents.md',
             'assets/NOTICES.md',
             'README.md',
         ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.3.28",
+  "version": "0.3.30",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -42,8 +42,8 @@
     "unified": "11.0.5",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.3.28",
-    "@open-agent-toolkit/docs-transforms": "0.3.28"
+    "@open-agent-toolkit/control-plane": "0.3.30",
+    "@open-agent-toolkit/docs-transforms": "0.3.30"
   },
   "devDependencies": {
     "@types/jsdom": "28.0.3",