@rasensio/aidlc 1.8.0 → 1.9.0

package/dist/operational/knowledge.js

@@ -0,0 +1,144 @@
+/**
+ * Knowledge-graph registration for operational skills.
+ *
+ * Registers each generated skill so `aidlc knowledge query <name>` finds it and a
+ * developer returning months later does not write a second skill for the same job
+ * (US-6, AC-28…AC-30, AC-49).
+ *
+ * Two properties are load-bearing and neither is free:
+ *
+ * - **The entity type is not gate-counted.** `custom:operational-skill` rather than
+ *   `module`, because the ideation seeding gate counts `module`, `convention`, and
+ *   `depends-on` (`knowledge/gate-criterion.ts`). Registering skills as modules
+ *   would let generated files satisfy a lifecycle gate meant to measure real
+ *   architecture.
+ * - **The id is namespaced and collisions are refused.** `addEntity` merges into any
+ *   pre-existing entity with the same id, and `mergeEntities` never overrides
+ *   `type` — so an unnamespaced id colliding with an existing `module` would stay
+ *   gate-counted *and* clobber an architecture fact. Registration therefore checks
+ *   the resolved type first and refuses rather than merging.
+ *
+ * Registration is best-effort: failure warns and generation still succeeds (AC-30).
+ *
+ * Requirements: AC-28, AC-29, AC-30, AC-49
+ *
+ * @module
+ */
+import { knowledgeExists, openKnowledge } from '../knowledge/engine.js';
+/** Entity type for operational skills — deliberately not gate-counted (AC-28). */
+export const OPERATIONAL_ENTITY_TYPE = 'custom:operational-skill';
+/** Id prefix keeping operational entities out of the general id namespace. */
+export const OPERATIONAL_ID_PREFIX = 'operational-skill-';
+/** Namespaced entity id for a skill name. */
+export function operationalEntityId(name) {
+    return `${OPERATIONAL_ID_PREFIX}${name}`;
+}
+/**
+ * Register (or repair) an operational skill in the knowledge graph.
+ *
+ * Never throws: a graph problem must not lose a skill the user already confirmed
+ * (AC-30). Re-running for a skill whose files exist but whose entity is missing
+ * recreates it, which is the AC-49 repair path.
+ *
+ * @param projectRoot - Absolute project root.
+ * @param skill - The skill to register.
+ * @returns Whether the entity is now present, plus any warning to surface.
+ */
+export function registerOperationalSkill(projectRoot, skill) {
+    const id = operationalEntityId(skill.meta.name);
+    // Projects that never adopted the knowledge graph are not forced into it.
+    if (!knowledgeExists(projectRoot)) {
+        return {
+            registered: false,
+            id,
+            warning: 'knowledge graph not initialized; skipped registration (run `aidlc knowledge add` later if wanted)',
+        };
+    }
+    let engine;
+    try {
+        engine = openKnowledge(projectRoot);
+    }
+    catch (err) {
+        return {
+            registered: false,
+            id,
+            warning: `could not open knowledge graph: ${err.message}`,
+        };
+    }
+    try {
+        // Refuse to merge across types. mergeEntities preserves the existing `type`,
+        // so merging here would silently rewrite someone else's record.
+        const existing = engine.index.getEntity(id);
+        if (existing && existing.type !== OPERATIONAL_ENTITY_TYPE) {
+            return {
+                registered: false,
+                id,
+                warning: `knowledge entity '${id}' already exists with type '${existing.type}'; ` +
+                    'refusing to overwrite it — the skill was written but not registered',
+            };
+        }
+        const result = engine.writer.addEntity({
+            id,
+            type: OPERATIONAL_ENTITY_TYPE,
+            name: skill.meta.name,
+            description: `Operational skill: ${skill.meta.description}`,
+            source: `.aidlc/operational-skills/${skill.meta.name}.md`,
+            tags: ['operational-skill', 'app-owned'],
+        });
+        return {
+            registered: true,
+            id,
+            ...(result.warnings.length > 0 ? { warning: result.warnings.join('; ') } : {}),
+        };
+    }
+    catch (err) {
+        return {
+            registered: false,
+            id,
+            warning: `registration failed: ${err.message}`,
+        };
+    }
+    finally {
+        try {
+            engine.close();
+        }
+        catch {
+            // Closing is best-effort; a close failure must not mask the result.
+        }
+    }
+}
+/**
+ * Is this skill already registered with the operational type?
+ *
+ * Used to decide whether a re-run needs to repair registration (AC-49).
+ *
+ * @param projectRoot - Absolute project root.
+ * @param name - Skill name.
+ */
+export function isOperationalSkillRegistered(projectRoot, name) {
+    if (!knowledgeExists(projectRoot))
+        return false;
+    let engine;
+    try {
+        engine = openKnowledge(projectRoot);
+    }
+    catch {
+        return false;
+    }
+    try {
+        const entity = engine.index.getEntity(operationalEntityId(name));
+        return entity?.type === OPERATIONAL_ENTITY_TYPE;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            engine.close();
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/operational/knowledge.js.map

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

package/dist/operational/packagers.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Per-platform packaging for operational skills.
+ *
+ * Mirrors the framework adapter seam — one canonical body, N platform-native
+ * files — but never passes through `loadSkills`/`parseSkillFile`, which require a
+ * lifecycle `phase` an operational skill does not have (D-1, AC-33).
+ *
+ * Two shapes, because two platforms have no natural one-skill-one-file form:
+ *
+ * - **Per-skill** (claude-code, kiro, cursor): one pointer file per skill.
+ * - **Index** (codex, windsurf): one artifact listing every operational skill.
+ *   Codex reads only `AGENTS.md`; windsurf has a per-file character budget that
+ *   O(n) rule files would exhaust.
+ *
+ * Every platform artifact is a **pointer** to the canonical body — the full
+ * instructions and the verification text live in
+ * `.aidlc/operational-skills/<name>.md` only. That scoping is what makes
+ * AC-35/AC-37/AC-38 well-defined.
+ *
+ * Requirements: AC-13, AC-14, AC-15, AC-16, AC-20, AC-47, AC-48
+ *
+ * @module
+ */
+import type { FileOp, PlatformId } from '../core/types.js';
+import type { OperationalSkill } from './schema.js';
+/** Directory holding canonical operational-skill bodies (AC-13, D-2). */
+export declare const OPERATIONAL_DIR = ".aidlc/operational-skills";
+/** Merge-block id for operational skills. Distinct from every framework id. */
+export declare const OPERATIONAL_BLOCK_ID = "aidlc-operational-skills";
+/** Windsurf index rule path — unprefixed, so it cannot collide with framework rules. */
+export declare const WINDSURF_INDEX_PATH = ".windsurf/rules/operational-skills.md";
+/**
+ * Build the app-owned marker comment.
+ *
+ * Placement differs per target because two adapters validate that their files
+ * *begin* with frontmatter (`claude-code.ts`, `cursor.ts`), so a first-line
+ * comment would fail their own validators.
+ */
+export declare function ownershipMarker(name: string): string;
+/** Packaging strategy for one platform. */
+export interface OperationalPackager {
+    readonly platform: PlatformId;
+    /** Per-skill file ops. Empty for index-shaped platforms. */
+    plan(skill: OperationalSkill): FileOp[];
+    /** One op covering all operational skills. Absent for per-skill platforms. */
+    planIndex?(skills: OperationalSkill[]): FileOp | null;
+}
+/** Thrown when a configured platform has no operational packaging (AC-16). */
+export declare class UnsupportedPlatformError extends Error {
+    readonly platform: string;
+    constructor(platform: string, supported: readonly string[]);
+}
+/** Relative path of a skill's canonical body. */
+export declare function canonicalBodyPath(name: string): string;
+/** Platforms with operational packaging, sorted for stable error messages. */
+export declare const supportedOperationalPlatforms: PlatformId[];
+/**
+ * Look up the packager for a platform.
+ *
+ * @param platform - Platform identifier from `.aidlc/config.yaml`.
+ * @returns The packager.
+ * @throws {UnsupportedPlatformError} When the platform has no packaging (AC-16).
+ */
+export declare function packagerFor(platform: PlatformId): OperationalPackager;
+/** Does this platform have operational packaging? */
+export declare function hasOperationalPackaging(platform: string): boolean;
+//# sourceMappingURL=packagers.d.ts.map

package/dist/operational/packagers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packagers.d.ts","sourceRoot":"","sources":["../../src/operational/packagers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAMpD,yEAAyE;AACzE,eAAO,MAAM,eAAe,8BAA8B,CAAC;AAE3D,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,6BAA6B,CAAC;AAE/D,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,0CAA0C,CAAC;AAM3E;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAWD,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,4DAA4D;IAC5D,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,EAAE,CAAC;IACxC,8EAA8E;IAC9E,SAAS,CAAC,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,GAAG,IAAI,CAAC;CACvD;AAED,8EAA8E;AAC9E,qBAAa,wBAAyB,SAAQ,KAAK;aAE/B,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM,EAChC,SAAS,EAAE,SAAS,MAAM,EAAE;CAQ/B;AAED,iDAAiD;AACjD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AA0LD,8EAA8E;AAC9E,eAAO,MAAM,6BAA6B,EAAE,UAAU,EAAiC,CAAC;AAExF;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,UAAU,GAAG,mBAAmB,CAMrE;AAED,qDAAqD;AACrD,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEjE"}

package/dist/operational/packagers.js

@@ -0,0 +1,252 @@
+/**
+ * Per-platform packaging for operational skills.
+ *
+ * Mirrors the framework adapter seam — one canonical body, N platform-native
+ * files — but never passes through `loadSkills`/`parseSkillFile`, which require a
+ * lifecycle `phase` an operational skill does not have (D-1, AC-33).
+ *
+ * Two shapes, because two platforms have no natural one-skill-one-file form:
+ *
+ * - **Per-skill** (claude-code, kiro, cursor): one pointer file per skill.
+ * - **Index** (codex, windsurf): one artifact listing every operational skill.
+ *   Codex reads only `AGENTS.md`; windsurf has a per-file character budget that
+ *   O(n) rule files would exhaust.
+ *
+ * Every platform artifact is a **pointer** to the canonical body — the full
+ * instructions and the verification text live in
+ * `.aidlc/operational-skills/<name>.md` only. That scoping is what makes
+ * AC-35/AC-37/AC-38 well-defined.
+ *
+ * Requirements: AC-13, AC-14, AC-15, AC-16, AC-20, AC-47, AC-48
+ *
+ * @module
+ */
+import { MAX_FILE_CHARS } from '../compile/limits.js';
+import { canonicalSkillFilename, normalizeSkillName } from '../compile/naming.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Directory holding canonical operational-skill bodies (AC-13, D-2). */
+export const OPERATIONAL_DIR = '.aidlc/operational-skills';
+/** Merge-block id for operational skills. Distinct from every framework id. */
+export const OPERATIONAL_BLOCK_ID = 'aidlc-operational-skills';
+/** Windsurf index rule path — unprefixed, so it cannot collide with framework rules. */
+export const WINDSURF_INDEX_PATH = '.windsurf/rules/operational-skills.md';
+// ---------------------------------------------------------------------------
+// Ownership marker (AC-20)
+// ---------------------------------------------------------------------------
+/**
+ * Build the app-owned marker comment.
+ *
+ * Placement differs per target because two adapters validate that their files
+ * *begin* with frontmatter (`claude-code.ts`, `cursor.ts`), so a first-line
+ * comment would fail their own validators.
+ */
+export function ownershipMarker(name) {
+    return `<!-- aidlc:operational-skill ${name} — app-owned, not framework-managed -->`;
+}
+/** Marker for an index artifact covering many skills. */
+function indexMarker() {
+    return '<!-- aidlc:operational-skills — app-owned, not framework-managed -->';
+}
+/** Thrown when a configured platform has no operational packaging (AC-16). */
+export class UnsupportedPlatformError extends Error {
+    platform;
+    constructor(platform, supported) {
+        super(`platform '${platform}' has no operational-skill packaging; ` +
+            `supported platforms are: ${supported.join(', ')}`);
+        this.platform = platform;
+        this.name = 'UnsupportedPlatformError';
+    }
+}
+/** Relative path of a skill's canonical body. */
+export function canonicalBodyPath(name) {
+    return `${OPERATIONAL_DIR}/${canonicalSkillFilename(name)}`;
+}
+/** Pointer sentence shared by every platform artifact. */
+function pointerLine(skill) {
+    return `Read \`${canonicalBodyPath(skill.meta.name)}\` and follow its instructions.`;
+}
+/**
+ * Platform directory/file segment for an operational skill.
+ *
+ * `prefix: false` is the whole point — the `aidlc-` namespace stays
+ * framework-owned (AC-19, AC-41).
+ */
+function segment(name) {
+    return normalizeSkillName(name, { prefix: false });
+}
+// ---------------------------------------------------------------------------
+// Per-skill packagers
+// ---------------------------------------------------------------------------
+/** claude-code: `.claude/skills/<name>/SKILL.md` (AC-14). */
+const claudeCodePackager = {
+    platform: 'claude-code',
+    plan(skill) {
+        const dir = segment(skill.meta.name);
+        // Frontmatter first — claude-code's validator requires `---\n` at byte 0.
+        const content = [
+            '---',
+            `name: ${dir}`,
+            `description: ${skill.meta.description}`,
+            '---',
+            '',
+            ownershipMarker(skill.meta.name),
+            '',
+            pointerLine(skill),
+            '',
+        ].join('\n');
+        return [{ kind: 'create', path: `.claude/skills/${dir}/SKILL.md`, content }];
+    },
+};
+/** kiro: `.kiro/skills/<name>/SKILL.md`. */
+const kiroPackager = {
+    platform: 'kiro',
+    plan(skill) {
+        const dir = segment(skill.meta.name);
+        const content = [
+            '---',
+            `name: ${dir}`,
+            `description: ${skill.meta.description}`,
+            '---',
+            '',
+            ownershipMarker(skill.meta.name),
+            '',
+            pointerLine(skill),
+            '',
+        ].join('\n');
+        return [{ kind: 'create', path: `.kiro/skills/${dir}/SKILL.md`, content }];
+    },
+};
+/**
+ * cursor: `.cursor/rules/<name>.mdc`.
+ *
+ * The marker rides in frontmatter as `aidlc_kind`. Cursor's validator requires
+ * only that `description:` and `alwaysApply:` be present, so an extra key is
+ * permitted — verified before relying on it.
+ */
+const cursorPackager = {
+    platform: 'cursor',
+    plan(skill) {
+        const file = `${segment(skill.meta.name)}.mdc`;
+        const content = [
+            '---',
+            `description: ${skill.meta.description}`,
+            'globs:',
+            'alwaysApply: false',
+            'aidlc_kind: operational',
+            '---',
+            '',
+            pointerLine(skill),
+            '',
+        ].join('\n');
+        return [{ kind: 'create', path: `.cursor/rules/${file}`, content }];
+    },
+};
+// ---------------------------------------------------------------------------
+// Index packagers
+// ---------------------------------------------------------------------------
+/** Shared index body: marker, heading, one bullet per skill. */
+function indexLines(skills) {
+    const lines = [indexMarker(), '', '# Operational Skills', ''];
+    if (skills.length === 0) {
+        lines.push('_No operational skills are defined in this project._');
+        return lines;
+    }
+    lines.push('App-owned skills for repeatable operations. Each entry points at its canonical', 'body; read that file and follow its instructions.', '');
+    // Sorted by name so output does not depend on directory-read order (AC-17).
+    for (const skill of [...skills].sort((a, b) => a.meta.name.localeCompare(b.meta.name))) {
+        lines.push(`- **${skill.meta.name}** — ${skill.meta.description}. ` +
+            `Read \`${canonicalBodyPath(skill.meta.name)}\`.`);
+    }
+    return lines;
+}
+/**
+ * codex: one merge-block in `AGENTS.md`.
+ *
+ * Shares the file with the framework block but never its id — the framework uses
+ * `aidlc` (`codex.ts:161`), and `mergeBlock` preserves every byte outside its own
+ * delimiters, so the two coexist (AC-43 as refined by DD-2).
+ */
+const codexPackager = {
+    platform: 'codex',
+    plan() {
+        return [];
+    },
+    planIndex(skills) {
+        if (skills.length === 0)
+            return null;
+        return {
+            kind: 'merge-block',
+            path: 'AGENTS.md',
+            blockId: OPERATIONAL_BLOCK_ID,
+            content: indexLines(skills).join('\n'),
+        };
+    },
+};
+/**
+ * windsurf: one index rule file.
+ *
+ * One file regardless of skill count, but O(n) characters within it — so the
+ * per-file cap binds sooner, not later. On exceeding it the index degrades to a
+ * directory pointer rather than dropping the list, which keeps operational skills
+ * discoverable (US-6). The cross-plan total budget is deliberately not enforced;
+ * see AC-48's recorded limitation.
+ */
+const windsurfPackager = {
+    platform: 'windsurf',
+    plan() {
+        return [];
+    },
+    planIndex(skills) {
+        if (skills.length === 0)
+            return null;
+        const full = indexLines(skills).join('\n') + '\n';
+        if (full.length <= MAX_FILE_CHARS) {
+            return { kind: 'create', path: WINDSURF_INDEX_PATH, content: full };
+        }
+        const degraded = [
+            indexMarker(),
+            '',
+            '# Operational Skills',
+            '',
+            `This project defines ${skills.length} app-owned operational skills — too many to`,
+            'list within the windsurf rule size limit.',
+            '',
+            `Read \`${OPERATIONAL_DIR}/\` and follow the instructions in the relevant skill.`,
+            '',
+        ].join('\n');
+        return { kind: 'create', path: WINDSURF_INDEX_PATH, content: degraded };
+    },
+};
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+const PACKAGERS = new Map([
+    ['claude-code', claudeCodePackager],
+    ['kiro', kiroPackager],
+    ['cursor', cursorPackager],
+    ['codex', codexPackager],
+    ['windsurf', windsurfPackager],
+]);
+/** Platforms with operational packaging, sorted for stable error messages. */
+export const supportedOperationalPlatforms = [...PACKAGERS.keys()].sort();
+/**
+ * Look up the packager for a platform.
+ *
+ * @param platform - Platform identifier from `.aidlc/config.yaml`.
+ * @returns The packager.
+ * @throws {UnsupportedPlatformError} When the platform has no packaging (AC-16).
+ */
+export function packagerFor(platform) {
+    const packager = PACKAGERS.get(platform);
+    if (!packager) {
+        throw new UnsupportedPlatformError(platform, supportedOperationalPlatforms);
+    }
+    return packager;
+}
+/** Does this platform have operational packaging? */
+export function hasOperationalPackaging(platform) {
+    return PACKAGERS.has(platform);
+}
+//# sourceMappingURL=packagers.js.map

package/dist/operational/packagers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"packagers.js","sourceRoot":"","sources":["../../src/operational/packagers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAGlF,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,yEAAyE;AACzE,MAAM,CAAC,MAAM,eAAe,GAAG,2BAA2B,CAAC;AAE3D,+EAA+E;AAC/E,MAAM,CAAC,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;AAE/D,wFAAwF;AACxF,MAAM,CAAC,MAAM,mBAAmB,GAAG,uCAAuC,CAAC;AAE3E,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,gCAAgC,IAAI,yCAAyC,CAAC;AACvF,CAAC;AAED,yDAAyD;AACzD,SAAS,WAAW;IAClB,OAAO,sEAAsE,CAAC;AAChF,CAAC;AAeD,8EAA8E;AAC9E,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAE/B;IADlB,YACkB,QAAgB,EAChC,SAA4B;QAE5B,KAAK,CACH,aAAa,QAAQ,wCAAwC;YAC3D,4BAA4B,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACrD,CAAC;QANc,aAAQ,GAAR,QAAQ,CAAQ;QAOhC,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,iDAAiD;AACjD,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,GAAG,eAAe,IAAI,sBAAsB,CAAC,IAAI,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED,0DAA0D;AAC1D,SAAS,WAAW,CAAC,KAAuB;IAC1C,OAAO,UAAU,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,iCAAiC,CAAC;AACvF,CAAC;AAED;;;;;GAKG;AACH,SAAS,OAAO,CAAC,IAAY;IAC3B,OAAO,kBAAkB,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;AACrD,CAAC;AAED,8EAA8E;AAC9E,sBAAsB;AACtB,8EAA8E;AAE9E,6DAA6D;AAC7D,MAAM,kBAAkB,GAAwB;IAC9C,QAAQ,EAAE,aAAa;IACvB,IAAI,CAAC,KAAK;QACR,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,0EAA0E;QAC1E,MAAM,OAAO,GAAG;YACd,KAAK;YACL,SAAS,GAAG,EAAE;YACd,gBAAgB,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE;YACxC,KAAK;YACL,EAAE;YACF,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;YAChC,EAAE;YACF,WAAW,CAAC,KAAK,CAAC;YAClB,EAAE;SACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACb,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,kBAAkB,GAAG,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;IAC/E,CAAC;CACF,CAAC;AAEF,4CAA4C;AAC5C,MAAM,YAAY,GAAwB;IACxC,QAAQ,EAAE,MAAM;IAChB,IAAI,CAAC,KAAK;QACR,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,OAAO,GAAG;YACd,KAAK;YACL,SAAS,GAAG,EAAE;YACd,gBAAgB,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE;YACxC,KAAK;YACL,EAAE;YACF,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;YAChC,EAAE;YACF,WAAW,CAAC,KAAK,CAAC;YAClB,EAAE;SACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACb,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,gBAAgB,GAAG,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7E,CAAC;CACF,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,cAAc,GAAwB;IAC1C,QAAQ,EAAE,QAAQ;IAClB,IAAI,CAAC,KAAK;QACR,MAAM,IAAI,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC;QAC/C,MAAM,OAAO,GAAG;YACd,KAAK;YACL,gBAAgB,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE;YACxC,QAAQ;YACR,oBAAoB;YACpB,yBAAyB;YACzB,KAAK;YACL,EAAE;YACF,WAAW,CAAC,KAAK,CAAC;YAClB,EAAE;SACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACb,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,iBAAiB,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IACtE,CAAC;CACF,CAAC;AAEF,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,gEAAgE;AAChE,SAAS,UAAU,CAAC,MAA0B;IAC5C,MAAM,KAAK,GAAG,CAAC,WAAW,EAAE,EAAE,EAAE,EAAE,sBAAsB,EAAE,EAAE,CAAC,CAAC;IAC9D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,sDAAsD,CAAC,CAAC;QACnE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,KAAK,CAAC,IAAI,CACR,gFAAgF,EAChF,mDAAmD,EACnD,EAAE,CACH,CAAC;IACF,4EAA4E;IAC5E,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QACvF,KAAK,CAAC,IAAI,CACR,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,QAAQ,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI;YACtD,UAAU,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CACpD,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,aAAa,GAAwB;IACzC,QAAQ,EAAE,OAAO;IACjB,IAAI;QACF,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,SAAS,CAAC,MAAM;QACd,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACrC,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,oBAAoB;YAC7B,OAAO,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;SACvC,CAAC;IACJ,CAAC;CACF,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,gBAAgB,GAAwB;IAC5C,QAAQ,EAAE,UAAU;IACpB,IAAI;QACF,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,SAAS,CAAC,MAAM;QACd,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAErC,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAClD,IAAI,IAAI,CAAC,MAAM,IAAI,cAAc,EAAE,CAAC;YAClC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACtE,CAAC;QAED,MAAM,QAAQ,GAAG;YACf,WAAW,EAAE;YACb,EAAE;YACF,sBAAsB;YACtB,EAAE;YACF,wBAAwB,MAAM,CAAC,MAAM,6CAA6C;YAClF,2CAA2C;YAC3C,EAAE;YACF,UAAU,eAAe,wDAAwD;YACjF,EAAE;SACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IAC1E,CAAC;CACF,CAAC;AAEF,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,MAAM,SAAS,GAAiD,IAAI,GAAG,CAAC;IACtE,CAAC,aAAa,EAAE,kBAAkB,CAAC;IACnC,CAAC,MAAM,EAAE,YAAY,CAAC;IACtB,CAAC,QAAQ,EAAE,cAAc,CAAC;IAC1B,CAAC,OAAO,EAAE,aAAa,CAAC;IACxB,CAAC,UAAU,EAAE,gBAAgB,CAAC;CAC/B,CAAC,CAAC;AAEH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,6BAA6B,GAAiB,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAExF;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,QAAoB;IAC9C,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACzC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,wBAAwB,CAAC,QAAQ,EAAE,6BAA6B,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,uBAAuB,CAAC,QAAgB;IACtD,OAAO,SAAS,CAAC,GAAG,CAAC,QAAsB,CAAC,CAAC;AAC/C,CAAC"}

package/dist/operational/redact.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Best-effort credential redaction for generated operational skills.
+ *
+ * Two rules, and the second matters as much as the first (AC-11):
+ *
+ * - Credential **values** are redacted. A generated skill is instructions an
+ *   agent will later execute, and it is committed to the repo, so a pasted token
+ *   would become a secret at rest (NFR-3).
+ * - Credential **references** are preserved. `$GITHUB_TOKEN`,
+ *   `op://vault/item/field`, `arn:aws:secretsmanager:...` are legitimate
+ *   operational content; stripping them would produce a skill that cannot work.
+ *
+ * **This is explicitly best-effort and not a security guarantee.** Detection is
+ * pattern- plus entropy-based, so novel credential formats will pass through. The
+ * real control is the confirmation gate: redaction runs *before* the preview is
+ * rendered (AC-44), so a human sees the redacted text and nothing reaches disk
+ * without their approval. Callers must not present this as a guarantee to users.
+ *
+ * Requirements: AC-11, AC-44, NFR-3
+ *
+ * @module
+ */
+/** Placeholder substituted for a redacted value. */
+export declare const REDACTION_PLACEHOLDER = "<REDACTED>";
+/** Result of a redaction pass. */
+export interface RedactionResult {
+    /** Text with detected credential values replaced. */
+    text: string;
+    /**
+     * Human-readable labels for what was redacted (never the values themselves —
+     * echoing them back would defeat the purpose).
+     */
+    redacted: string[];
+}
+/**
+ * Redact credential values from text, preserving credential references.
+ *
+ * @param text - Text that may contain credentials.
+ * @returns The redacted text plus labels describing what was removed.
+ */
+export declare function redactSecrets(text: string): RedactionResult;
+/**
+ * Convenience: did this text contain anything that looked like a credential?
+ *
+ * @param text - Text to inspect.
+ * @returns True when `redactSecrets` would change the text.
+ */
+export declare function containsSecrets(text: string): boolean;
+//# sourceMappingURL=redact.d.ts.map

package/dist/operational/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/operational/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,oDAAoD;AACpD,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAElD,kCAAkC;AAClC,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAgED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAkC3D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/operational/redact.js

@@ -0,0 +1,135 @@
+/**
+ * Best-effort credential redaction for generated operational skills.
+ *
+ * Two rules, and the second matters as much as the first (AC-11):
+ *
+ * - Credential **values** are redacted. A generated skill is instructions an
+ *   agent will later execute, and it is committed to the repo, so a pasted token
+ *   would become a secret at rest (NFR-3).
+ * - Credential **references** are preserved. `$GITHUB_TOKEN`,
+ *   `op://vault/item/field`, `arn:aws:secretsmanager:...` are legitimate
+ *   operational content; stripping them would produce a skill that cannot work.
+ *
+ * **This is explicitly best-effort and not a security guarantee.** Detection is
+ * pattern- plus entropy-based, so novel credential formats will pass through. The
+ * real control is the confirmation gate: redaction runs *before* the preview is
+ * rendered (AC-44), so a human sees the redacted text and nothing reaches disk
+ * without their approval. Callers must not present this as a guarantee to users.
+ *
+ * Requirements: AC-11, AC-44, NFR-3
+ *
+ * @module
+ */
+/** Placeholder substituted for a redacted value. */
+export const REDACTION_PLACEHOLDER = '<REDACTED>';
+/**
+ * Named provider token shapes. Anchored on distinctive prefixes so they do not
+ * fire on ordinary prose.
+ */
+const TOKEN_PATTERNS = [
+    { label: 'GitHub token', re: /\bgh[pousr]_[A-Za-z0-9]{16,}\b/g },
+    { label: 'GitHub fine-grained token', re: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g },
+    { label: 'AWS access key id', re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
+    { label: 'Slack token', re: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g },
+    { label: 'Google API key', re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+    { label: 'Stripe key', re: /\b[sr]k_(?:live|test)_[0-9A-Za-z]{16,}\b/g },
+    { label: 'OpenAI key', re: /\bsk-[A-Za-z0-9]{20,}\b/g },
+    { label: 'Anthropic key', re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g },
+    { label: 'npm token', re: /\bnpm_[A-Za-z0-9]{30,}\b/g },
+    { label: 'JSON Web Token', re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g },
+    { label: 'private key block', re: /-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z ]+ )?PRIVATE KEY-----/g },
+];
+/**
+ * `KEY=value` / `key: value` assignments whose *name* implies a secret. The value
+ * is redacted only when it is a literal — a `$VAR` or secret-manager reference on
+ * the right-hand side is a reference, not a value, and is kept.
+ */
+const ASSIGNMENT_RE = /\b([A-Za-z_][A-Za-z0-9_]*(?:SECRET|TOKEN|PASSWORD|PASSWD|APIKEY|API_KEY|ACCESS_KEY|PRIVATE_KEY|CREDENTIAL)[A-Za-z0-9_]*)\s*[:=]\s*(['"]?)([^\s'"#]+)\2/gi;
+/**
+ * Right-hand sides that are references rather than values, and must survive.
+ * Preserving these is required by AC-11, not merely nice to have.
+ */
+const REFERENCE_RE = /^(?:\$|\$\{|%|<|op:\/\/|vault:|secret:|arn:aws:secretsmanager:|projects\/[^/]+\/secrets\/|sm:\/\/|env:|process\.env)/i;
+/** Shannon entropy in bits per character. */
+function entropy(s) {
+    const freq = new Map();
+    for (const ch of s)
+        freq.set(ch, (freq.get(ch) ?? 0) + 1);
+    let h = 0;
+    for (const n of freq.values()) {
+        const p = n / s.length;
+        h -= p * Math.log2(p);
+    }
+    return h;
+}
+/**
+ * Does this look like a high-entropy secret rather than a word or a path?
+ *
+ * Conservative on purpose: a false positive silently mangles a legitimate skill,
+ * and the confirmation gate is the real backstop.
+ */
+function looksLikeSecret(token) {
+    if (token.length < 24)
+        return false;
+    if (REFERENCE_RE.test(token))
+        return false;
+    // Paths, URLs, and dotted identifiers are common and are not secrets.
+    if (/[/\\]/.test(token) || token.includes('://'))
+        return false;
+    // Require mixed character classes — long lowercase words are not secrets.
+    const classes = [/[a-z]/, /[A-Z]/, /[0-9]/].filter((re) => re.test(token)).length;
+    if (classes < 2)
+        return false;
+    return entropy(token) >= 3.5;
+}
+/**
+ * Redact credential values from text, preserving credential references.
+ *
+ * @param text - Text that may contain credentials.
+ * @returns The redacted text plus labels describing what was removed.
+ */
+export function redactSecrets(text) {
+    const redacted = [];
+    let out = text;
+    // 1. Named provider token shapes.
+    for (const { label, re } of TOKEN_PATTERNS) {
+        out = out.replace(re, () => {
+            if (!redacted.includes(label))
+                redacted.push(label);
+            return REDACTION_PLACEHOLDER;
+        });
+    }
+    // 2. Secret-named assignments with a literal right-hand side.
+    out = out.replace(ASSIGNMENT_RE, (match, key, quote, value) => {
+        if (REFERENCE_RE.test(value))
+            return match; // a reference — preserve (AC-11)
+        if (value === REDACTION_PLACEHOLDER)
+            return match; // already handled above
+        const label = `value assigned to ${key}`;
+        if (!redacted.includes(label))
+            redacted.push(label);
+        return `${key}=${quote}${REDACTION_PLACEHOLDER}${quote}`.replace('=', match.includes(':') && !match.includes('=') ? ': ' : '=');
+    });
+    // 3. Free-standing high-entropy strings.
+    out = out.replace(/[A-Za-z0-9+/_=-]{24,}/g, (token) => {
+        if (token === REDACTION_PLACEHOLDER)
+            return token;
+        if (!looksLikeSecret(token))
+            return token;
+        const label = 'high-entropy string';
+        if (!redacted.includes(label))
+            redacted.push(label);
+        return REDACTION_PLACEHOLDER;
+    });
+    return { text: out, redacted };
+}
+/**
+ * Convenience: did this text contain anything that looked like a credential?
+ *
+ * @param text - Text to inspect.
+ * @returns True when `redactSecrets` would change the text.
+ */
+export function containsSecrets(text) {
+    return redactSecrets(text).redacted.length > 0;
+}
+//# sourceMappingURL=redact.js.map