@angelmsger/fx 0.0.0-stage → 0.11.0

package/dist/domain/diagnostics.js

@@ -0,0 +1,49 @@
+// Diagnostic redaction keeps troubleshooting useful without moving credentials
+// or unbounded companion output onto fx's stderr data channel.
+const SECRET_FLAG = /^--?(?:api[-_]?key|auth|credential|password|secret|token)$/i;
+const SECRET_ASSIGNMENT = /^(--?(?:api[-_]?key|auth|credential|password|secret|token))=(.*)$/i;
+const URL_CREDENTIALS = /(https?:\/\/[^\s:/@]+:)[^\s@]+@/gi;
+const BEARER = /(\b(?:authorization\s*:\s*)?bearer\s+)[^\s,;]+/gi;
+const ASSIGNMENT = /(\b(?:api[-_]?key|password|secret|token)\s*[=:]\s*)[^\s,;]+/gi;
+const LIMIT = 4096;
+export function redactVector(vector) {
+    let hidesNext = false;
+    return vector.map((argument) => {
+        if (hidesNext) {
+            hidesNext = false;
+            return '[REDACTED]';
+        }
+        if (SECRET_FLAG.test(argument)) {
+            hidesNext = true;
+            return argument;
+        }
+        const assigned = SECRET_ASSIGNMENT.exec(argument);
+        if (assigned !== null)
+            return `${assigned[1] ?? ''}=[REDACTED]`;
+        return redactText(argument);
+    });
+}
+export function redactText(input) {
+    return input
+        .replace(URL_CREDENTIALS, '$1[REDACTED]@')
+        .replace(BEARER, '$1[REDACTED]')
+        .replace(ASSIGNMENT, '$1[REDACTED]');
+}
+export function summarizeDiagnostic(input) {
+    const text = redactText(input.trim());
+    if (text === '')
+        return undefined;
+    if (text.length <= LIMIT)
+        return text;
+    return `[truncated ${text.length - LIMIT} chars]\n${text.slice(-LIMIT)}`;
+}
+export function causeChain(error) {
+    const chain = [];
+    let current = error;
+    for (let depth = 0; depth < 5 && current instanceof Error; depth += 1) {
+        chain.push(redactText(`${current.name}: ${current.message}`));
+        current = current.cause;
+    }
+    return chain;
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/domain/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/domain/diagnostics.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,+DAA+D;AAE/D,MAAM,WAAW,GAAG,6DAA6D,CAAC;AAClF,MAAM,iBAAiB,GAAG,oEAAoE,CAAC;AAC/F,MAAM,eAAe,GAAG,mCAAmC,CAAC;AAC5D,MAAM,MAAM,GAAG,kDAAkD,CAAC;AAClE,MAAM,UAAU,GAAG,+DAA+D,CAAC;AACnF,MAAM,KAAK,GAAG,IAAI,CAAC;AAmBnB,MAAM,UAAU,YAAY,CAAC,MAAyB;IACpD,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;QAC7B,IAAI,SAAS,EAAE,CAAC;YACd,SAAS,GAAG,KAAK,CAAC;YAClB,OAAO,YAAY,CAAC;QACtB,CAAC;QACD,IAAI,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC/B,SAAS,GAAG,IAAI,CAAC;YACjB,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,MAAM,QAAQ,GAAG,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAClD,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,aAAa,CAAC;QAChE,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAK;SACT,OAAO,CAAC,eAAe,EAAE,eAAe,CAAC;SACzC,OAAO,CAAC,MAAM,EAAE,cAAc,CAAC;SAC/B,OAAO,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACtC,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAClC,IAAI,IAAI,CAAC,MAAM,IAAI,KAAK;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,cAAc,IAAI,CAAC,MAAM,GAAG,KAAK,YAAY,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAY;IACrC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,GAAY,KAAK,CAAC;IAC7B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,IAAI,OAAO,YAAY,KAAK,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACtE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC9D,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/domain/distribution.js

@@ -0,0 +1,22 @@
+// @ts-check
+// Distribution identity varies by channel; the project and executable remain fx-devkit/fx.
+export const DISTRIBUTIONS = {
+    internal: { packageName: '@fx/devkit', access: 'restricted' },
+    public: { packageName: '@angelmsger/fx', access: 'public' },
+};
+export const PUBLIC_REGISTRY = 'https://registry.npmjs.org/';
+/** @param {unknown} value */
+export function distribution(value) {
+    if (value !== 'internal' && value !== 'public')
+        throw new Error('Choose internal or public distribution.');
+    return DISTRIBUTIONS[value];
+}
+/** @param {string} name */
+export function packageChannel(name) {
+    if (name === DISTRIBUTIONS.internal.packageName)
+        return 'internal';
+    if (name === DISTRIBUTIONS.public.packageName)
+        return 'public';
+    throw new Error('Unknown fx distribution package.');
+}
+//# sourceMappingURL=distribution.js.map

package/dist/domain/distribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"distribution.js","sourceRoot":"","sources":["../../src/domain/distribution.js"],"names":[],"mappings":"AAAA,YAAY;AACZ,2FAA2F;AAC3F,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,QAAQ,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE;IAC7D,MAAM,EAAE,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,EAAE,QAAQ,EAAE;CAC5D,CAAC;AACF,MAAM,CAAC,MAAM,eAAe,GAAG,6BAA6B,CAAC;AAC7D,6BAA6B;AAC7B,MAAM,UAAU,YAAY,CAAC,KAAK;IAChC,IAAI,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK,QAAQ;QAC5C,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AACD,2BAA2B;AAC3B,MAAM,UAAU,cAAc,CAAC,IAAI;IACjC,IAAI,IAAI,KAAK,aAAa,CAAC,QAAQ,CAAC,WAAW;QAAE,OAAO,UAAU,CAAC;IACnE,IAAI,IAAI,KAAK,aAAa,CAAC,MAAM,CAAC,WAAW;QAAE,OAAO,QAAQ,CAAC;IAC/D,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;AACtD,CAAC"}

package/dist/domain/docs/derived.js

@@ -0,0 +1,13 @@
+// A file fx derives into the workspace root announces itself on its first
+// line, so fx can tell its own output from a person's file and never
+// replace the latter.
+const PREFIX = '<!-- fx:derived ';
+export const DERIVED_GUIDE = 'AGENTS.md';
+// Claude Code reads the guide itself, and reads this file in its place whenever it
+// exists. fx therefore derives none: a marked copy is the pointer earlier versions
+// wrote and is removed, and any other belongs to the person.
+export const CLAUDE_GUIDE = 'CLAUDE.md';
+export const marker = (origin) => `${PREFIX}from ${origin}; regenerated by fx sync, edit the origin instead -->`;
+export const isDerived = (text) => text.startsWith(PREFIX);
+export const derive = (text, origin) => `${marker(origin)}\n${text}`;
+//# sourceMappingURL=derived.js.map

package/dist/domain/docs/derived.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived.js","sourceRoot":"","sources":["../../../src/domain/docs/derived.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,qEAAqE;AACrE,sBAAsB;AAEtB,MAAM,MAAM,GAAG,kBAAkB,CAAC;AAElC,MAAM,CAAC,MAAM,aAAa,GAAG,WAAW,CAAC;AAEzC,mFAAmF;AACnF,mFAAmF;AACnF,6DAA6D;AAC7D,MAAM,CAAC,MAAM,YAAY,GAAG,WAAW,CAAC;AAExC,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,MAAc,EAAU,EAAE,CAC/C,GAAG,MAAM,QAAQ,MAAM,uDAAuD,CAAC;AAEjF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,IAAY,EAAW,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AAE5E,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,MAAc,EAAU,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC"}

package/dist/domain/docs/regions.js

@@ -0,0 +1,94 @@
+// Replace fx-owned regions while preserving author text. Source rendering reports
+// missing regions; generated workspace guides may append them through completeRegions.
+import { DevkitError } from '../errors.js';
+export const begin = (name) => `<!-- fx:begin ${name} -->`;
+export const end = (name) => `<!-- fx:end ${name} -->`;
+const MARKER = /<!-- fx:begin ([a-z0-9-]+) -->/g;
+const BOUNDARY = /<!-- fx:(begin|end) ([a-z0-9-]+) -->/g;
+const RETIRED = new Set(['rules']);
+export function completeRegions(doc, regions) {
+    const seen = new Set();
+    let opening;
+    for (const marker of doc.matchAll(BOUNDARY)) {
+        const name = marker[2];
+        if (marker[1] === 'begin') {
+            if (opening !== undefined || seen.has(name))
+                throw invalidRegions(name);
+            opening = name;
+            seen.add(name);
+        }
+        else {
+            if (opening !== name)
+                throw invalidRegions(name);
+            opening = undefined;
+        }
+    }
+    if (opening !== undefined)
+        throw invalidRegions(opening);
+    const rendered = renderRegions(doc, regions);
+    const added = rendered.missing;
+    const suffix = added.map((name) => region(name, regions[name])).join('\n\n');
+    return {
+        ...rendered,
+        text: suffix
+            ? `${rendered.text}${rendered.text.endsWith('\n') ? '\n' : '\n\n'}${suffix}\n`
+            : rendered.text,
+        missing: [],
+        added,
+    };
+}
+function invalidRegions(name) {
+    return new DevkitError('conflict', 'DOCS_REGIONS_INVALID', `The guide has ambiguous fx markers near ${name}`, {
+        hint: 'Nested, duplicate and unclosed regions are preserved rather than rewritten.',
+        nextSteps: ['Repair the marker pairs in the source AGENTS.md, then retry initialization.'],
+    });
+}
+export function renderRegions(doc, regions) {
+    const present = [...doc.matchAll(MARKER)].map((m) => m[1] ?? '');
+    const replaced = [];
+    let text = removeRetired(doc);
+    for (const [name, body] of Object.entries(regions)) {
+        const from = text.indexOf(begin(name));
+        const to = text.indexOf(end(name), from);
+        if (from === -1 || to === -1)
+            continue;
+        text = `${text.slice(0, from + begin(name).length)}\n${body.trim()}\n${text.slice(to)}`;
+        replaced.push(name);
+    }
+    return {
+        text,
+        replaced,
+        missing: Object.keys(regions).filter((name) => !replaced.includes(name)),
+        unknown: present.filter((name) => !(name in regions)),
+    };
+}
+// Only an unambiguous top-level pair is removable. A nested or malformed
+// block may contain human-owned markers, so leave that whole block alone.
+function removeRetired(doc) {
+    const stack = [];
+    const spans = [];
+    let nested = false;
+    for (const marker of doc.matchAll(BOUNDARY)) {
+        if (marker[1] === 'begin') {
+            if (stack.length === 0)
+                nested = false;
+            else
+                nested = true;
+            stack.push(marker);
+            continue;
+        }
+        const opening = stack.pop();
+        if (opening === undefined || stack.length > 0 || nested)
+            continue;
+        if (opening[2] === marker[2] && RETIRED.has(opening[2] ?? ''))
+            spans.push({ start: opening.index, end: marker.index + marker[0].length });
+    }
+    let text = doc;
+    for (const span of spans.reverse())
+        text = text.slice(0, span.start) + text.slice(span.end);
+    return text;
+}
+export function region(name, body) {
+    return `${begin(name)}\n${body.trim()}\n${end(name)}`;
+}
+//# sourceMappingURL=regions.js.map

package/dist/domain/docs/regions.js.map

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

package/dist/domain/docs/skeleton.js

@@ -0,0 +1,14 @@
+// The AGENTS.md a fresh workspace starts from: a title, one sentence on how
+// the file works, and the active regions, empty. Prose belongs outside them.
+import { region } from './regions.js';
+import { REGIONS } from './templates.js';
+export function agentsSkeleton(workspaceName) {
+    return [
+        `# ${workspaceName} workspace`,
+        '',
+        'This workspace is built and kept in step by `fx`. The blocks between `<!-- fx:begin … -->` and `<!-- fx:end … -->` are generated from the manifest by `fx manifest render` in the manifest repository and are replaced as a whole; write routing rules, conventions and anything else people should know **outside** them.',
+        '',
+        ...REGIONS.flatMap((name) => [region(name, ''), '']),
+    ].join('\n');
+}
+//# sourceMappingURL=skeleton.js.map

package/dist/domain/docs/skeleton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skeleton.js","sourceRoot":"","sources":["../../../src/domain/docs/skeleton.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,6EAA6E;AAE7E,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAEzC,MAAM,UAAU,cAAc,CAAC,aAAqB;IAClD,OAAO;QACL,KAAK,aAAa,YAAY;QAC9B,EAAE;QACF,4TAA4T;QAC5T,EAAE;QACF,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;KACrD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/domain/docs/templates.js

@@ -0,0 +1,169 @@
+// The generated regions of AGENTS.md: what an agent needs before it loads any Skill or
+// asks fx anything. Facts that vary by person or machine — coordinates, credentials,
+// versions, people — stay out; the text points at the fx command that answers instead.
+import { CAPABILITY_INFO, knownCapability, } from '../capability.js';
+import { WORKBENCH_DIR } from '../workspace/root-entries.js';
+export const REGIONS = [
+    'project-index',
+    'capabilities',
+    'environments',
+    'ask-fx',
+    'workspace-layout',
+    'team-skills',
+];
+export function renderAll(input) {
+    return {
+        'project-index': projectIndex(input.workspace),
+        capabilities: capabilities(input),
+        environments: environments(input.environments),
+        'ask-fx': askFx(),
+        'workspace-layout': workspaceLayout(),
+        'team-skills': teamSkillIndex(input.teamSkills ?? []),
+    };
+}
+export function projectIndex(workspace) {
+    const groups = new Map();
+    for (const repo of workspace.repos) {
+        const tag = repo.tags?.[0] ?? 'other';
+        groups.set(tag, [...(groups.get(tag) ?? []), repo]);
+    }
+    const lines = [
+        '## Repositories',
+        '',
+        'One line per repository, grouped by its first tag. `fx repo show <name>` has the rest.',
+        'This catalog includes repositories not downloaded yet. When a task needs one, use `fx repo show <name>` and follow its `next_steps` to select and synchronize it, then continue the task in its checkout.',
+    ];
+    for (const [tag, repos] of [...groups.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        lines.push('', `### ${tag}`, '', '| Repository | Project | Description |', '| --- | --- | --- |');
+        for (const repo of repos) {
+            const project = repo.project ?? workspace.defaults.upstream_project ?? '';
+            lines.push(`| \`${repo.name}\` | ${project} | ${cell(repo.desc)} |`);
+        }
+    }
+    return lines.join('\n');
+}
+const WHEN = {
+    'code-host': 'read or fork a repository, open a pull request',
+    'issue-tracker': 'find or update a work item',
+    'knowledge-base': 'read team documentation',
+    im: 'message a person or a group',
+    calendar: 'find an event or when someone is free',
+    meeting: 'schedule or look up an online meeting, its recording or minutes',
+    task: 'track a to-do',
+    worklog: 'record or review time spent',
+    'error-tracker': 'look at runtime errors of a service',
+    'log-store': 'search the logs of a service',
+    metrics: 'query the metrics of a service',
+    ci: 'check a build or its console output',
+    cluster: 'see what is running (read-only)',
+};
+export function capabilities(input) {
+    const lines = [
+        '## Capabilities',
+        '',
+        'What the workspace can reach, who provides it, and the command to run **before** using the tool. `fx can` answers whether it works on this machine right now and explains what is missing when it does not; `fx where <repo> --env <env>` answers per platform for one repository, with the coordinate.',
+        '',
+        '| Need to | Capability | Provider | Tool | Ask fx first |',
+        '| --- | --- | --- | --- | --- |',
+    ];
+    const workspaceRows = input.bindings
+        .filter((b) => b.provider !== null)
+        .map((b) => row(b.capability, b.provider ?? '', input, `fx can ${b.capability}`));
+    const platformRows = input.platforms
+        .filter((b) => b.provider !== null)
+        .map((b) => row(b.capability, b.provider ?? '', input, `fx where <repo> --env <env> --platform ${b.platform}`));
+    lines.push(...workspaceRows, ...platformRows);
+    lines.push('', 'People and ownership are not a capability: `fx member show <name>`; `fx repo show <repo>` names the owners.');
+    return lines.join('\n');
+}
+function row(capability, provider, input, command) {
+    const known = knownCapability(capability);
+    const when = known === null ? capability : (WHEN[known] ?? CAPABILITY_INFO[known].desc);
+    const tools = input
+        .toolsOf(provider)
+        .map((name) => input.tools.find((t) => t.name === name)?.binary ?? name)
+        .map((t) => `\`${t}\``)
+        .join(', ');
+    return `| ${when} | ${capability} | ${provider} | ${tools} | \`${command}\` |`;
+}
+export function environments(doc) {
+    const lines = ['## Environments', ''];
+    if (doc === undefined) {
+        lines.push('This workspace declares no environments.');
+        return lines.join('\n');
+    }
+    lines.push('Names and what each one is. Coordinates (projects, streams, jobs, namespaces) are not written here: `fx where <repo> --env <env>` derives them from the manifest.', '', '| Environment | Label | Platforms | Note |', '| --- | --- | --- | --- |');
+    for (const [name, env] of Object.entries(doc.envs)) {
+        lines.push(`| \`${name}\` | ${cell(env.label)} | ${Object.keys(env.platforms ?? {}).join(', ')} | ${cell(env.note)} |`);
+    }
+    return lines.join('\n');
+}
+export function askFx() {
+    return [
+        '## Ask fx',
+        '',
+        'Start with the read-only command `fx self info --format json`. Verify `name` is `@fx/devkit` (internal) or `@angelmsger/fx` (public) and check `version`, then read `SKILL.md` inside the returned `bundled_skill` directory. A valid response establishes the entry for this task; do not repeat wrapper, package-file or `--version` probes for the same entry. A matching executable name or a global Skill copy alone does not establish identity.',
+        '',
+        'If the command is missing, cannot start or returns a different identity, use `command -v fx` (or the shell equivalent) and inspect the resolved executable/package. Read the manifest source README for the team installation source. In a derived guide the first-line `fx:derived from` marker locates that source; otherwise use this manifest checkout. This recovery works without fx.',
+        '',
+        'For recovery, use only a verified installation or a local checkout identified by package.json as `@fx/devkit` or `@angelmsger/fx` with bin `fx`. Check its runtime requirements and README; an available build can run as `node <checkout>/bin/fx.js` without global installation. If runtime/dependencies/build are missing, perform authorized local preparation from that README. Do not guess a package registry, publication state, credentials or a checkout outside this workspace. If no usable source is documented or reachable, ask for that specific source/access and retain the original task.',
+        '',
+        'After recovering or changing the entry, repeat `self info --format json` and load its bundled Skill. Keep using the verified entry; no Skill-loaded environment declaration is required. A startup failure is a runtime/PATH/source problem to diagnose; do not repeat an unchanged failure.',
+        '',
+        'Coordinates, people, tool state and machine setup are answered by `fx`, always with `--format json` when an agent is asking. Do not guess any of them.',
+        '',
+        '`fx` answers; you act. It prints the command a coordinate resolves to and never runs it — running it is yours to do, once `fx` says the platform is ready.',
+        '',
+        '| Question | Command |',
+        '| --- | --- |',
+        '| Where are the errors / logs / builds / pods of a service, and can I use them now | `fx where <repo> --env <env>` |',
+        '| Can I use a capability or tool right now | `fx can <capability\\|tool> [--env <env>]` |',
+        '| Who is this person; who owns this repository | `fx member show <name>`; `fx repo show <repo>` |',
+        '| Is this machine set up; what is missing | `fx doctor`; `fx login --list` |',
+        '| What environments exist | `fx env list`; `fx env show <env>` |',
+        '',
+        'For a non-ready answer or `LOGIN_REQUIRED`, follow the Skill recovery flow: inspect the cause, perform authorized local installation/setup, hand off only necessary human interaction, then re-check the same capability and resume the original task. A handoff is guidance, not authorization: preserve read-only posture and exact-command trust; do not repeat an unchanged failure or overwrite existing configuration without approval and backup.',
+    ].join('\n');
+}
+export function workspaceLayout() {
+    const bench = WORKBENCH_DIR;
+    return [
+        '## Workspace layout',
+        '',
+        `The workspace root holds repository checkouts and fx-managed agent resources, nothing else. It is not a Git repository, so nothing there reports or ignores a new file. Everything a task produces outside a repository goes under \`${bench}/\` at the workspace root.`,
+        '',
+        '| Path | Holds | Lifetime |',
+        '| --- | --- | --- |',
+        `| \`${bench}/<YYYY-MM-DD>-<topic>/\` | One directory per task: reports, plans, evidence, demos, one-off scripts | Kept. Never renamed or moved once something cites it |`,
+        `| \`${bench}/worktrees/<repo>-<topic>/\` | Targets of \`git worktree add\` for a repository | Until the branch lands; then \`git worktree remove\` |`,
+        `| \`${bench}/tmp/\` | Anything reproducible or bulky: downloads, clones, sandbox roots, dependency trees, raw dumps | Disposable at any time |`,
+        '',
+        '- Date a task directory by the day the task started and keep using it across sessions.',
+        "- Files needed only within one session belong in the agent's own scratch directory or the system temporary directory.",
+        `- Cite \`${bench}/\` paths relative to the workspace root. Never cite anything under \`tmp/\` from memory, documents or reports.`,
+        '- Work with its own source and lifecycle is a repository: create it, then `fx repo add <path>`.',
+        '- Do not create other files or directories at the workspace root. `fx doctor` lists the ones that are there.',
+    ].join('\n');
+}
+function cell(text) {
+    return (text ?? '').replaceAll('|', '\\|').replaceAll('\n', ' ');
+}
+export function teamSkillIndex(skills) {
+    const lines = [
+        '## Team Skills',
+        '',
+        'The fx-workspace companion Skill teaches the fx CLI and readiness recovery. These manifest Skills supply team workflows. Read the matching SKILL.md when its description fits the task; follow its references only as needed. Do not load every Skill at once.',
+        '',
+        'These source links provide discovery even when native project Skill delivery is unavailable. A listing does not prove installation, host trust or loading. Start the agent at the workspace root; child-repository sessions are not covered by this guide.',
+        '',
+    ];
+    if (skills.length === 0)
+        return [...lines, 'This manifest contains no team Skills.'].join('\n');
+    lines.push('| Skill | When to use | Read |', '| --- | --- | --- |');
+    for (const skill of skills) {
+        const target = skill.source.split('/').map(encodeURIComponent).join('/');
+        lines.push(`| ${cell(skill.name)} | ${cell(skill.description)} | [SKILL.md](<${target}>) |`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=templates.js.map

package/dist/domain/docs/templates.js.map

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

package/dist/domain/errors.js

@@ -0,0 +1,156 @@
+// The shared structured failure and recovery contract; category determines the command exit code.
+export const CATEGORIES = [
+    'usage',
+    'config',
+    'auth',
+    'permission',
+    'not_found',
+    'conflict',
+    'rate_limit',
+    'network',
+    'server',
+    'parse',
+    'internal',
+    'incomplete',
+];
+const EXIT_CODE = {
+    internal: 1,
+    usage: 2,
+    config: 3,
+    auth: 4,
+    permission: 5,
+    not_found: 6,
+    rate_limit: 7,
+    network: 8,
+    server: 9,
+    parse: 10,
+    conflict: 11,
+    incomplete: 12,
+};
+const RETRYABLE = new Set(['rate_limit', 'network', 'server']);
+const GUIDANCE = {
+    incomplete: {
+        hint: 'Completed work is preserved. Resolve the reported blockers, then continue.',
+        nextSteps: ['fx init --resume --workspace <name>'],
+    },
+    usage: { hint: 'The command was invoked incorrectly.', nextSteps: ['fx <command> --help'] },
+    config: {
+        hint: 'The configuration or workspace state is missing or invalid.',
+        nextSteps: ['fx doctor', 'fx config list'],
+    },
+    auth: {
+        hint: 'A companion tool rejected or lacks credentials.',
+        nextSteps: ['fx doctor', 'fx login <tool>'],
+    },
+    permission: {
+        hint: 'The operation is not allowed with the current access or posture.',
+        nextSteps: ['fx doctor'],
+    },
+    not_found: {
+        hint: 'The named repository, environment, tool or key does not exist.',
+        nextSteps: ['fx repo list', 'fx env list', 'fx tool list'],
+    },
+    conflict: {
+        hint: 'Local state diverged from what the command expected. Inspect the reported outcome before retrying.',
+        nextSteps: ['fx status', 'Resolve the local state, then retry.'],
+    },
+    rate_limit: { hint: 'A service is throttling requests.', nextSteps: ['Wait, then retry.'] },
+    network: {
+        hint: 'A service could not be reached.',
+        nextSteps: ['Check connectivity and VPN, then retry.'],
+    },
+    server: { hint: 'A service returned an internal error.', nextSteps: ['Retry later.'] },
+    parse: {
+        hint: 'A document or tool output could not be parsed.',
+        nextSteps: ['Retry with --verbose to inspect the raw input.'],
+    },
+    internal: {
+        hint: 'An unexpected internal error occurred.',
+        nextSteps: ['Retry with --verbose and report the output.'],
+    },
+};
+// The line a person reads for a step's check: what it said, or what the step waits on.
+export function checkNote(step) {
+    if (step.check === undefined)
+        return undefined;
+    return step.check.result === 'failed'
+        ? `Check: ${step.check.detail}`
+        : `Waits on ${step.check.by}`;
+}
+export class DevkitError extends Error {
+    category;
+    code;
+    hint;
+    nextSteps;
+    retryable;
+    handoff;
+    diagnostics;
+    partialResult;
+    constructor(category, code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.category = category;
+        this.code = code;
+        this.name = 'DevkitError';
+        this.hint = options.hint ?? GUIDANCE[category].hint;
+        this.nextSteps = options.nextSteps ?? GUIDANCE[category].nextSteps;
+        this.retryable = options.retryable ?? RETRYABLE.has(category);
+        this.handoff = options.handoff;
+        this.diagnostics = options.diagnostics ?? [];
+        this.partialResult = options.partialResult;
+    }
+}
+// Lease contention: every caller holds a resource another fx process wants, so
+// the failure is always retryable and recovery is to run the command again.
+export function busyError(code, resource, options = {}) {
+    return new DevkitError('conflict', code, `${resource} is busy`, {
+        retryable: true,
+        hint: 'Another fx process holds this lease.',
+        nextSteps: options.nextSteps ?? ['Retry the command shortly.'],
+    });
+}
+export function defaultGuidance(category) {
+    return GUIDANCE[category];
+}
+export function exitCodeFor(category) {
+    return EXIT_CODE[category];
+}
+export function asDevkitError(err) {
+    if (err instanceof DevkitError)
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    return new DevkitError('internal', 'INTERNAL', message, { cause: err });
+}
+export function toEnvelope(err) {
+    const base = {
+        category: err.category,
+        code: err.code,
+        message: err.message,
+        hint: err.hint,
+        next_steps: err.nextSteps,
+        retryable: err.retryable,
+    };
+    return { error: err.handoff ? { ...base, handoff: handoffEnvelope(err.handoff) } : base };
+}
+export function handoffEnvelope(handoff) {
+    return {
+        summary: handoff.summary,
+        user_steps: handoff.userSteps,
+        ...(handoff.command === undefined ? {} : { command: handoff.command }),
+        ...(handoff.alternatives === undefined ? {} : { alternatives: handoff.alternatives }),
+    };
+}
+// A failed workflow can still have completed effects. Preserve the original
+// failure contract while carrying a separately rendered machine result.
+export function withPartialResult(error, result) {
+    const failure = asDevkitError(error);
+    return new DevkitError(failure.category, failure.code, failure.message, {
+        hint: failure.hint,
+        nextSteps: failure.nextSteps,
+        retryable: failure.retryable,
+        ...(failure.handoff === undefined ? {} : { handoff: failure.handoff }),
+        diagnostics: failure.diagnostics,
+        cause: failure,
+        partialResult: result,
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/domain/errors.js.map

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

package/dist/domain/format.js

@@ -0,0 +1,8 @@
+// The three output formats and the default, named once so the flag, the config
+// key and the docs generator cannot disagree about them.
+export const FORMATS = ['human', 'json', 'ndjson'];
+export const DEFAULT_FORMAT = 'human';
+export function isFormat(value) {
+    return typeof value === 'string' && FORMATS.includes(value);
+}
+//# sourceMappingURL=format.js.map

package/dist/domain/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/domain/format.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,yDAAyD;AAEzD,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAU,CAAC;AAE5D,MAAM,CAAC,MAAM,cAAc,GAAW,OAAO,CAAC;AAE9C,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,OAA6B,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACrF,CAAC"}

package/dist/domain/fuzzy.js

@@ -0,0 +1,26 @@
+// "Did you mean" for every place a name can be mistyped: commands, config
+// keys, later repos, tools and agents. One implementation so the correction
+// reads the same everywhere.
+export function levenshtein(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const substitution = (previous[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1);
+            current[j] = Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, substitution);
+        }
+        previous = current;
+    }
+    return previous[b.length] ?? 0;
+}
+export function nearest(name, candidates, maxDistance = 3) {
+    let best;
+    for (const candidate of candidates) {
+        const distance = levenshtein(name, candidate);
+        if (distance <= maxDistance && (best === undefined || distance < best.distance)) {
+            best = { candidate, distance };
+        }
+    }
+    return best?.candidate;
+}
+//# sourceMappingURL=fuzzy.js.map

package/dist/domain/fuzzy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fuzzy.js","sourceRoot":"","sources":["../../src/domain/fuzzy.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,4EAA4E;AAC5E,6BAA6B;AAE7B,MAAM,UAAU,WAAW,CAAC,CAAS,EAAE,CAAS;IAC9C,IAAI,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACjE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC;QACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACnC,MAAM,YAAY,GAAG,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC9E,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,CAAC;QACzF,CAAC;QACD,QAAQ,GAAG,OAAO,CAAC;IACrB,CAAC;IACD,OAAO,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,OAAO,CACrB,IAAY,EACZ,UAA6B,EAC7B,WAAW,GAAG,CAAC;IAEf,IAAI,IAAyD,CAAC;IAC9D,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC9C,IAAI,QAAQ,IAAI,WAAW,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAChF,IAAI,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;QACjC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,EAAE,SAAS,CAAC;AACzB,CAAC"}

package/dist/domain/harness/hooks.js

@@ -0,0 +1,10 @@
+// Lifecycle definitions are host-neutral data. Hosts translate event names
+// and output, while the single dispatch vector keeps behavior in fx.
+export const BUILTIN_HOOKS = [
+    {
+        event: 'session-start',
+        command: ['fx', 'hook', 'dispatch', 'session-start'],
+        background: false,
+    },
+];
+//# sourceMappingURL=hooks.js.map

package/dist/domain/harness/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../../src/domain/harness/hooks.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,qEAAqE;AA2BrE,MAAM,CAAC,MAAM,aAAa,GAAwB;IAChD;QACE,KAAK,EAAE,eAAe;QACtB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,CAAC;QACpD,UAAU,EAAE,KAAK;KAClB;CACF,CAAC"}