agentic-workflow-manager 3.0.1 → 3.1.0

package/dist/src/commands/export.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runExportCommand = runExportCommand;
+exports.registerExportCommand = registerExportCommand;
+const picocolors_1 = __importDefault(require("picocolors"));
+const path_1 = __importDefault(require("path"));
+const export_1 = require("../core/export");
+function runExportCommand(name, flags, deps = {}) {
+    const log = deps.log ?? console.log;
+    const opts = {
+        name,
+        target: flags.target,
+        out: flags.out,
+        roots: deps.roots,
+        zip: deps.zip,
+    };
+    const summary = (0, export_1.runExport)(opts);
+    log(picocolors_1.default.dim(`Exported ${summary.kind} "${name}"`));
+    for (const e of summary.exported) {
+        log(picocolors_1.default.green(`✓ ${e.name}`) + picocolors_1.default.dim(` → ${e.zip ?? e.dir}`));
+    }
+    if (summary.skipped.length > 0) {
+        log(picocolors_1.default.dim(`Skipped (not portable): ${summary.skipped.join(', ')}`));
+    }
+    if (!summary.zipAvailable) {
+        log(picocolors_1.default.yellow('zip binary not found — folders were written without archives.'));
+        log(picocolors_1.default.dim(`Compress manually, e.g.: cd ${summary.outDir} && zip -r <skill>.zip <skill>`));
+    }
+    log(picocolors_1.default.dim(`Output: ${path_1.default.resolve(summary.outDir)}`));
+}
+function registerExportCommand(program) {
+    program.command('export <name>')
+        .description('Export a bundle or skill as claude.ai-uploadable custom skill artifacts (folder + zip)')
+        .option('--target <target>', 'export target', 'claude-ai')
+        .option('--out <dir>', 'output directory (default: ./awm-export)')
+        .action((name, flags) => {
+        try {
+            runExportCommand(name, flags);
+        }
+        catch (e) {
+            console.error(picocolors_1.default.red(e instanceof Error ? e.message : String(e)));
+            process.exit(1);
+        }
+    });
+}

package/dist/src/core/discovery.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchFrontmatterBlock = matchFrontmatterBlock;
 exports.readArtifactDescription = readArtifactDescription;
 exports.discoverSkills = discoverSkills;
 exports.discoverWorkflows = discoverWorkflows;
@@ -11,13 +12,18 @@ exports.discoverAgents = discoverAgents;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const registries_1 = require("./registries");
+/** Extracts the raw frontmatter text (between the --- delimiters), or null if the block is missing/malformed. CRLF-tolerant. */
+function matchFrontmatterBlock(raw) {
+    const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    return fmMatch ? fmMatch[1] : null;
+}
 function readArtifactDescription(filePath) {
     try {
         const raw = fs_1.default.readFileSync(filePath, 'utf-8');
-        const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-        if (!fmMatch)
+        const frontmatter = matchFrontmatterBlock(raw);
+        if (frontmatter === null)
             return '';
-        const line = fmMatch[1]
+        const line = frontmatter
             .split(/\r?\n/)
             .find((l) => /^description\s*:/.test(l));
         if (!line)

package/dist/src/core/export/index.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPORT_TARGETS = void 0;
+exports.runExport = runExport;
+// cli/src/core/export/index.ts
+//
+// Orquestación del export (issue #9): resolve → adapt (override verbatim R3,
+// o transform mecánico R3.1) → pack. Opera 100% offline (R5.2): solo fs local.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const registries_1 = require("../registries");
+const resolve_1 = require("./resolve");
+const transform_1 = require("./transform");
+const pack_1 = require("./pack");
+exports.EXPORT_TARGETS = ['claude-ai'];
+function runExport(opts) {
+    const target = opts.target ?? 'claude-ai';
+    if (!exports.EXPORT_TARGETS.includes(target)) {
+        throw new Error(`Unknown export target "${target}". Valid targets: ${exports.EXPORT_TARGETS.join(', ')}.`);
+    }
+    const roots = opts.roots ?? (0, registries_1.contentRoots)();
+    const outDir = path_1.default.join(opts.out ?? path_1.default.join(process.cwd(), 'awm-export'), target);
+    const resolution = (0, resolve_1.resolveExport)(opts.name, roots);
+    fs_1.default.mkdirSync(outDir, { recursive: true });
+    const exported = [];
+    let zipAvailable = true;
+    for (const skill of resolution.skills) {
+        let adapted;
+        if (skill.overridePath) {
+            adapted = fs_1.default.readFileSync(skill.overridePath, 'utf-8'); // R3: verbatim
+        }
+        else {
+            const canonical = path_1.default.join(skill.dir, 'SKILL.md');
+            const raw = fs_1.default.readFileSync(canonical, 'utf-8');
+            try {
+                adapted = (0, transform_1.claudeAiTransform)(raw, skill.name);
+            }
+            catch (e) {
+                throw new Error(`${canonical}: ${e instanceof Error ? e.message : String(e)}`); // R3.4 cita el archivo
+            }
+        }
+        const packed = (0, pack_1.packSkill)({ name: skill.name, adaptedSkillMd: adapted, srcDir: skill.dir, targetRoot: outDir, zip: opts.zip });
+        if (packed.zipMissing)
+            zipAvailable = false;
+        exported.push({ name: skill.name, dir: packed.dir, zip: packed.zip });
+    }
+    return { outDir, kind: resolution.kind, exported, skipped: resolution.skipped, zipAvailable };
+}

package/dist/src/core/export/pack.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultZip = void 0;
+exports.packSkill = packSkill;
+// cli/src/core/export/pack.ts
+//
+// Escritura determinística del artefacto (R4: limpia su propio subárbol antes
+// de escribir) + zip por capas con binario del sistema (R4.1/R4.2). ZipFn es
+// inyectable para tests.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+/** Refuses symlinks anywhere in the tree — copying/zipping them could dereference
+ * into content outside the registry (info-leak) or embed a broken/unexpected
+ * link for the recipient. Exported artifacts are plain files only. */
+function assertNoSymlinks(dir) {
+    for (const entry of fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+        const full = path_1.default.join(dir, entry.name);
+        if (entry.isSymbolicLink()) {
+            throw new Error(`Refusing to export "${full}": symlinks are not supported in exported artifacts (could leak file content via zip dereferencing, or resolve unexpectedly for the recipient).`);
+        }
+        if (entry.isDirectory())
+            assertNoSymlinks(full);
+    }
+}
+/** Capa 1: binario `zip` del sistema. ENOENT → missing (capa 2: carpeta). */
+const defaultZip = (cwd, zipName, folderName) => {
+    const r = (0, child_process_1.spawnSync)('zip', ['-r', '-q', zipName, folderName], { cwd });
+    if (r.error && r.error.code === 'ENOENT') {
+        return { ok: false, missing: true };
+    }
+    return { ok: r.status === 0, missing: false };
+};
+exports.defaultZip = defaultZip;
+function packSkill(opts) {
+    const zip = opts.zip ?? exports.defaultZip;
+    const skillOut = path_1.default.join(opts.targetRoot, opts.name);
+    const zipPath = path_1.default.join(opts.targetRoot, `${opts.name}.zip`);
+    // R4: determinismo — el re-export limpia su propio subárbol primero.
+    fs_1.default.rmSync(skillOut, { recursive: true, force: true });
+    fs_1.default.rmSync(zipPath, { force: true });
+    fs_1.default.mkdirSync(skillOut, { recursive: true });
+    fs_1.default.writeFileSync(path_1.default.join(skillOut, 'SKILL.md'), opts.adaptedSkillMd);
+    const refs = path_1.default.join(opts.srcDir, 'references');
+    if (fs_1.default.existsSync(refs)) {
+        assertNoSymlinks(refs);
+        fs_1.default.cpSync(refs, path_1.default.join(skillOut, 'references'), { recursive: true }); // R3.2 byte-idéntico
+    }
+    const zr = zip(opts.targetRoot, `${opts.name}.zip`, opts.name);
+    if (zr.missing)
+        return { dir: skillOut, zip: null, zipMissing: true };
+    if (!zr.ok)
+        throw new Error(`zip failed for skill "${opts.name}" (non-zero exit).`);
+    return { dir: skillOut, zip: zipPath, zipMissing: false };
+}

package/dist/src/core/export/resolve.js

@@ -0,0 +1,77 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveExport = resolveExport;
+// cli/src/core/export/resolve.ts
+//
+// Resolución <nombre> → skills a exportar (R1/R1.1) con gate de portabilidad
+// (R2.x) y consistencia de override (R3.3). Lee SIEMPRE de content roots del
+// registry instalado — nunca de ~/.claude/skills.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const bundles_1 = require("../bundles");
+const discovery_1 = require("../discovery");
+const OVERRIDE_FILE = 'port.claude-ai.md';
+/** portable: true en el frontmatter (bloque --- inicial), CRLF-tolerant como readArtifactDescription en discovery.ts. */
+function isPortable(skillMd) {
+    const frontmatter = (0, discovery_1.matchFrontmatterBlock)(skillMd);
+    if (frontmatter === null)
+        return false;
+    return /^portable\s*:\s*true\s*$/m.test(frontmatter);
+}
+/**
+ * Delegates skill location to discoverSkills(roots) so the SAME collision/override
+ * contract used by bundles/workflows/agents applies here (R3): a same-named skill in
+ * two roots throws unless the later root's awm-registry.json declares it in "overrides",
+ * in which case the later root's version wins. Locating manually (first-root-wins) would
+ * silently resolve to the wrong registry's version — see Finding 1.
+ */
+function locate(skillName, roots) {
+    const found = (0, discovery_1.discoverSkills)(roots).find((s) => s.name === skillName);
+    if (!found)
+        return null;
+    const dir = found.path;
+    const skillFile = path_1.default.join(dir, 'SKILL.md');
+    const overridePath = fs_1.default.existsSync(path_1.default.join(dir, OVERRIDE_FILE))
+        ? path_1.default.join(dir, OVERRIDE_FILE) : null;
+    return { name: skillName, dir, portable: isPortable(fs_1.default.readFileSync(skillFile, 'utf-8')), overridePath };
+}
+/** R3.3: un override declara intención de export; sin portable es contrato a medias. */
+function assertOverrideConsistency(s) {
+    if (s.overridePath && !s.portable) {
+        throw new Error(`Inconsistent metadata for skill "${s.name}": ${OVERRIDE_FILE} exists but SKILL.md does not declare portable: true.`);
+    }
+}
+function resolveExport(requested, roots) {
+    const bundles = (0, bundles_1.discoverAllBundles)(roots);
+    if (bundles.some((b) => b.name === requested)) {
+        const skills = [];
+        const skipped = [];
+        for (const name of (0, bundles_1.resolveBundleSkills)(requested, bundles)) {
+            const s = locate(name, roots);
+            if (!s)
+                throw new Error(`Bundle "${requested}" lists skill "${name}" but no content root contains skills/${name}/SKILL.md.`);
+            assertOverrideConsistency(s);
+            if (s.portable)
+                skills.push(s);
+            else
+                skipped.push(s.name);
+        }
+        if (skills.length === 0) {
+            throw new Error(`Bundle "${requested}" has no portable skills — nothing to export. Mark skills with portable: true in their frontmatter.`);
+        }
+        return { kind: 'bundle', requested, skills, skipped: skipped.sort() };
+    }
+    const single = locate(requested, roots);
+    if (!single) {
+        const available = bundles.map((b) => b.name).join(', ') || '(none)';
+        throw new Error(`"${requested}" is neither a bundle nor a skill in any content root. Available bundles: ${available}.`);
+    }
+    assertOverrideConsistency(single);
+    if (!single.portable) {
+        throw new Error(`Skill "${requested}" is not portable (no portable: true in its frontmatter) — it likely depends on filesystem/git and would break on claude.ai.`);
+    }
+    return { kind: 'skill', requested, skills: [single], skipped: [] };
+}

package/dist/src/core/export/transform.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFERENCE_LINE = void 0;
+exports.claudeAiTransform = claudeAiTransform;
+// cli/src/core/export/transform.ts
+//
+// Transform mecánico claude.ai (R3.1): función pura string → string.
+// Frontmatter line-based plano (los SKILL.md del baseline usan claves de una
+// línea) — sin parser YAML a propósito (YAGNI, cero deps).
+const DEFERENCE_LINE = (skillName) => `In environments with AWM installed (Claude Code), defer to the registry's ${skillName} skill — this port is for environments without filesystem access.`;
+exports.DEFERENCE_LINE = DEFERENCE_LINE;
+function claudeAiTransform(skillMd, skillName) {
+    // \r?\n-tolerant, same rationale as readArtifactDescription in discovery.ts:
+    // SKILL.md files may be CRLF-terminated and that's still valid frontmatter.
+    const startMatch = skillMd.match(/^---\r?\n/);
+    if (!startMatch) {
+        throw new Error('missing frontmatter block (file must start with ---)');
+    }
+    const startLen = startMatch[0].length;
+    const endMatch = skillMd.slice(startLen).match(/\r?\n---\r?\n/);
+    if (!endMatch || endMatch.index === undefined) {
+        throw new Error('unterminated frontmatter block (closing --- not found)');
+    }
+    const end = startLen + endMatch.index;
+    const body = skillMd.slice(end + endMatch[0].length);
+    const fmLines = skillMd.slice(startLen, end).split(/\r?\n/)
+        .filter((l) => !/^(version|portable):/.test(l));
+    const descIdx = fmLines.findIndex((l) => /^description:/.test(l));
+    if (descIdx === -1) {
+        throw new Error('frontmatter has no description field');
+    }
+    const descLine = fmLines[descIdx];
+    const value = descLine.slice('description:'.length).trim();
+    if (value === '' || value === '>' || value === '|' || value.startsWith('>') || value.startsWith('|')) {
+        throw new Error('description must be single-line (block scalars are not supported by the export transform)');
+    }
+    const deference = (0, exports.DEFERENCE_LINE)(skillName);
+    // Quote-style detection mirrors readArtifactDescription in discovery.ts: both
+    // single- and double-quoted scalars are first-class, and we work off the
+    // trimmed value so trailing whitespace after a closing quote doesn't fool us.
+    const isDoubleQuoted = value.length >= 2 && value.startsWith('"') && value.endsWith('"');
+    const isSingleQuoted = value.length >= 2 && value.startsWith("'") && value.endsWith("'");
+    if ((value.startsWith('"') || value.startsWith("'")) && !isDoubleQuoted && !isSingleQuoted) {
+        throw new Error('description has trailing content after its closing quote (e.g. an inline comment) — not supported by the export transform; remove the comment or use a port.claude-ai.md override');
+    }
+    // YAML single-quoted scalars escape a literal ' by doubling it (''); the
+    // deference text ("...registry's..." — see DEFERENCE_LINE) contains an
+    // apostrophe, so it must be escaped before splicing into a single-quoted
+    // description or it would prematurely close the YAML string.
+    const newValue = isDoubleQuoted
+        ? `${value.slice(0, -1)} ${deference}"`
+        : isSingleQuoted
+            ? `${value.slice(0, -1)} ${deference.replace(/'/g, "''")}'`
+            : `${value} ${deference}`;
+    fmLines[descIdx] = `description: ${newValue}`;
+    return `---\n${fmLines.join('\n')}\n---\n${body}`;
+}

package/dist/src/core/export/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/index.js

@@ -34,6 +34,7 @@ const doctor_1 = require("./commands/doctor");
 const init_1 = require("./commands/init");
 const registry_1 = require("./commands/registry");
 const pin_1 = require("./commands/pin");
+const export_1 = require("./commands/export");
 const profile_pins_1 = require("./core/profile-pins");
 const update_check_1 = require("./core/update-check");
 const paths_1 = require("./core/paths");
@@ -801,4 +802,5 @@ miroCmd.command('sync <storyMapPath>')
 (0, init_1.registerInitCommand)(program);
 (0, registry_1.registerRegistryCommand)(program);
 (0, pin_1.registerPinCommands)(program);
+(0, export_1.registerExportCommand)(program);
 program.parse();

package/dist/tests/commands/export.test.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const export_1 = require("../../src/commands/export");
+const okZip = (cwd, zipName) => {
+    fs_1.default.writeFileSync(path_1.default.join(cwd, zipName), 'fake-zip');
+    return { ok: true, missing: false };
+};
+function makeRoot() {
+    const root = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-cmd-root-'));
+    fs_1.default.mkdirSync(path_1.default.join(root, 'bundles/dev'), { recursive: true });
+    fs_1.default.writeFileSync(path_1.default.join(root, 'catalog.json'), JSON.stringify({
+        version: 1,
+        bundles: [{ name: 'dev', source: './bundles/dev', version: '1.0.0', scope: 'baseline' }],
+    }));
+    fs_1.default.writeFileSync(path_1.default.join(root, 'bundles/dev/bundle.json'), JSON.stringify({
+        name: 'dev', version: '1.0.0', scope: 'baseline', dependsOn: [],
+        skills: ['proc-skill', { name: 'mermaid', onSignal: true }], workflows: [], agents: [],
+    }));
+    const mk = (name, fm) => {
+        const dir = path_1.default.join(root, 'skills', name);
+        fs_1.default.mkdirSync(dir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(dir, 'SKILL.md'), `---\n${fm.join('\n')}\n---\nBody.\n`);
+    };
+    mk('proc-skill', ['name: proc-skill', 'description: "P."']);
+    mk('mermaid', ['name: mermaid', 'portable: true', 'description: "D."']);
+    return root;
+}
+describe('runExportCommand (salida al usuario)', () => {
+    let root;
+    let out;
+    let logs;
+    const log = (m) => logs.push(m);
+    beforeEach(() => {
+        root = makeRoot();
+        out = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-cmd-out-'));
+        logs = [];
+    });
+    afterEach(() => {
+        fs_1.default.rmSync(root, { recursive: true, force: true });
+        fs_1.default.rmSync(out, { recursive: true, force: true });
+    });
+    it('reports exported skills and visible skips', () => {
+        (0, export_1.runExportCommand)('dev', { target: 'claude-ai', out }, { roots: [root], zip: okZip, log });
+        const text = logs.join('\n');
+        expect(text).toMatch(/exported bundle.*dev/i);
+        expect(text).toContain('mermaid');
+        expect(text).toMatch(/skipped.*proc-skill/i);
+    });
+    it('prints the manual-zip instruction when the binary is missing', () => {
+        const missingZip = () => ({ ok: false, missing: true });
+        (0, export_1.runExportCommand)('dev', { target: 'claude-ai', out }, { roots: [root], zip: missingZip, log });
+        expect(logs.join('\n')).toMatch(/zip -r/);
+    });
+    it('propagates unknown-target errors (commander action will exit(1))', () => {
+        expect(() => (0, export_1.runExportCommand)('dev', { target: 'nope', out }, { roots: [root], zip: okZip, log }))
+            .toThrow(/Valid targets/);
+    });
+});

package/dist/tests/core/export/engine.test.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const export_1 = require("../../../src/core/export");
+const okZip = (cwd, zipName) => {
+    fs_1.default.writeFileSync(path_1.default.join(cwd, zipName), 'fake-zip');
+    return { ok: true, missing: false };
+};
+/** Mismo fixture que resolve.test.ts (root falso con bundle dev + 3 skills). */
+function makeRoot() {
+    const root = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-engine-root-'));
+    fs_1.default.mkdirSync(path_1.default.join(root, 'bundles/dev'), { recursive: true });
+    fs_1.default.writeFileSync(path_1.default.join(root, 'catalog.json'), JSON.stringify({
+        version: 1,
+        bundles: [{ name: 'dev', source: './bundles/dev', version: '1.0.0', scope: 'baseline' }],
+    }));
+    fs_1.default.writeFileSync(path_1.default.join(root, 'bundles/dev/bundle.json'), JSON.stringify({
+        name: 'dev', version: '1.0.0', scope: 'baseline', dependsOn: [],
+        skills: ['proc-skill', { name: 'mermaid', onSignal: true }, { name: 'ported', onSignal: true }],
+        workflows: [], agents: [],
+    }));
+    const mk = (name, fm) => {
+        const dir = path_1.default.join(root, 'skills', name);
+        fs_1.default.mkdirSync(dir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(dir, 'SKILL.md'), `---\n${fm.join('\n')}\n---\nBody of ${name}.\n`);
+        return dir;
+    };
+    mk('proc-skill', ['name: proc-skill', 'description: "Process skill."']);
+    const mermaid = mk('mermaid', ['name: mermaid', 'version: "1.0.0"', 'portable: true', 'description: "Diagrams."']);
+    fs_1.default.mkdirSync(path_1.default.join(mermaid, 'references'));
+    fs_1.default.writeFileSync(path_1.default.join(mermaid, 'references/flow.md'), 'flow reference bytes');
+    const ported = mk('ported', ['name: ported', 'portable: true', 'description: "Ported."']);
+    fs_1.default.writeFileSync(path_1.default.join(ported, 'port.claude-ai.md'), '---\nname: ported\ndescription: "Custom port."\n---\nOverride body, verbatim.\n');
+    return root;
+}
+describe('runExport (engine end-to-end)', () => {
+    let root;
+    let out;
+    beforeEach(() => {
+        root = makeRoot();
+        out = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-engine-out-'));
+    });
+    afterEach(() => {
+        fs_1.default.rmSync(root, { recursive: true, force: true });
+        fs_1.default.rmSync(out, { recursive: true, force: true });
+    });
+    it('exports a bundle: transform for mermaid, verbatim override for ported, skips proc-skill', () => {
+        const summary = (0, export_1.runExport)({ name: 'dev', out, roots: [root], zip: okZip });
+        expect(summary.kind).toBe('bundle');
+        expect(summary.exported.map((e) => e.name).sort()).toEqual(['mermaid', 'ported']);
+        expect(summary.skipped).toEqual(['proc-skill']);
+        const mermaidMd = fs_1.default.readFileSync(path_1.default.join(out, 'claude-ai/mermaid/SKILL.md'), 'utf-8');
+        expect(mermaidMd).not.toMatch(/^version:/m);
+        expect(mermaidMd).not.toMatch(/^portable:/m);
+        expect(mermaidMd).toContain('defer to the registry');
+        expect(fs_1.default.readFileSync(path_1.default.join(out, 'claude-ai/mermaid/references/flow.md'), 'utf-8')).toBe('flow reference bytes');
+        const portedMd = fs_1.default.readFileSync(path_1.default.join(out, 'claude-ai/ported/SKILL.md'), 'utf-8');
+        expect(portedMd).toBe('---\nname: ported\ndescription: "Custom port."\n---\nOverride body, verbatim.\n'); // cero transforms
+    });
+    it('rejects an unknown target listing the valid ones', () => {
+        expect(() => (0, export_1.runExport)({ name: 'dev', target: 'hermes', out, roots: [root], zip: okZip }))
+            .toThrow(new RegExp(export_1.EXPORT_TARGETS.join('|')));
+    });
+    it('wraps transform errors with the offending file path', () => {
+        // portable: true se mantiene (si no, resolve.ts corta antes por R2.x y nunca llega
+        // a transform.ts); lo que rompe es la ausencia de "description:", que transform.ts exige.
+        fs_1.default.writeFileSync(path_1.default.join(root, 'skills/mermaid/SKILL.md'), '---\nname: mermaid\nportable: true\n---\nNo description field.\n');
+        expect(() => (0, export_1.runExport)({ name: 'mermaid', out, roots: [root], zip: okZip }))
+            .toThrow(/mermaid[/\\]SKILL\.md/);
+    });
+    it('reads only the provided roots (never ~/.claude/skills)', () => {
+        // La lectura sale exclusivamente de roots: un root vacío no resuelve nada.
+        // Control negativo real: contentRoots() (el fallback al registry instalado)
+        // no debe invocarse en absoluto cuando opts.roots viene dado explícitamente.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const registries = require('../../../src/core/registries');
+        const spy = jest.spyOn(registries, 'contentRoots');
+        const empty = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-empty-root-'));
+        expect(() => (0, export_1.runExport)({ name: 'mermaid', out, roots: [empty], zip: okZip })).toThrow(/neither a bundle nor a skill/);
+        expect(spy).not.toHaveBeenCalled();
+        spy.mockRestore();
+        fs_1.default.rmSync(empty, { recursive: true, force: true });
+    });
+    it('defaults --out to ./awm-export/<target> under the current working directory', () => {
+        const cwdTmp = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-engine-cwd-'));
+        const originalCwd = process.cwd();
+        process.chdir(cwdTmp);
+        try {
+            const summary = (0, export_1.runExport)({ name: 'mermaid', roots: [root], zip: okZip }); // sin `out`
+            expect(summary.outDir).toBe(path_1.default.join(cwdTmp, 'awm-export', 'claude-ai'));
+            expect(fs_1.default.existsSync(path_1.default.join(cwdTmp, 'awm-export/claude-ai/mermaid/SKILL.md'))).toBe(true);
+        }
+        finally {
+            process.chdir(originalCwd);
+            fs_1.default.rmSync(cwdTmp, { recursive: true, force: true });
+        }
+    });
+});

package/dist/tests/core/export/pack.test.js

@@ -0,0 +1,122 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const pack_1 = require("../../../src/core/export/pack");
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const childProcess = require('child_process');
+const okZip = (cwd, zipName) => {
+    fs_1.default.writeFileSync(path_1.default.join(cwd, zipName), 'fake-zip');
+    return { ok: true, missing: false };
+};
+const missingZip = () => ({ ok: false, missing: true });
+describe('packSkill', () => {
+    let src;
+    let out;
+    beforeEach(() => {
+        src = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-pack-src-'));
+        out = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-pack-out-'));
+        fs_1.default.writeFileSync(path_1.default.join(src, 'SKILL.md'), 'canonical');
+        fs_1.default.mkdirSync(path_1.default.join(src, 'references'));
+        fs_1.default.writeFileSync(path_1.default.join(src, 'references/a.md'), 'ref-A bytes');
+    });
+    afterEach(() => {
+        fs_1.default.rmSync(src, { recursive: true, force: true });
+        fs_1.default.rmSync(out, { recursive: true, force: true });
+    });
+    it('writes adapted SKILL.md and byte-identical references', () => {
+        const r = (0, pack_1.packSkill)({ name: 'x', adaptedSkillMd: 'adapted', srcDir: src, targetRoot: out, zip: okZip });
+        expect(fs_1.default.readFileSync(path_1.default.join(out, 'x/SKILL.md'), 'utf-8')).toBe('adapted');
+        expect(fs_1.default.readFileSync(path_1.default.join(out, 'x/references/a.md'), 'utf-8')).toBe('ref-A bytes');
+        expect(r.zip).toBe(path_1.default.join(out, 'x.zip'));
+    });
+    it('re-export cleans its own subtree first (stale files gone)', () => {
+        fs_1.default.mkdirSync(path_1.default.join(out, 'x'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(out, 'x/stale.md'), 'old');
+        fs_1.default.writeFileSync(path_1.default.join(out, 'x.zip'), 'old-zip');
+        (0, pack_1.packSkill)({ name: 'x', adaptedSkillMd: 'adapted', srcDir: src, targetRoot: out, zip: missingZip });
+        expect(fs_1.default.existsSync(path_1.default.join(out, 'x/stale.md'))).toBe(false);
+        expect(fs_1.default.existsSync(path_1.default.join(out, 'x.zip'))).toBe(false);
+    });
+    it('falls back to folder-only when zip binary is missing', () => {
+        const r = (0, pack_1.packSkill)({ name: 'x', adaptedSkillMd: 'adapted', srcDir: src, targetRoot: out, zip: missingZip });
+        expect(r.zip).toBeNull();
+        expect(r.zipMissing).toBe(true);
+        expect(fs_1.default.existsSync(path_1.default.join(out, 'x/SKILL.md'))).toBe(true);
+    });
+    it('skill without references/ packs SKILL.md alone', () => {
+        fs_1.default.rmSync(path_1.default.join(src, 'references'), { recursive: true });
+        (0, pack_1.packSkill)({ name: 'x', adaptedSkillMd: 'adapted', srcDir: src, targetRoot: out, zip: okZip });
+        expect(fs_1.default.existsSync(path_1.default.join(out, 'x/references'))).toBe(false);
+    });
+    it('throws when the zip function reports a real failure (not missing binary)', () => {
+        const failingZip = () => ({ ok: false, missing: false });
+        expect(() => (0, pack_1.packSkill)({ name: 'x', adaptedSkillMd: 'adapted', srcDir: src, targetRoot: out, zip: failingZip }))
+            .toThrow(/zip failed/);
+    });
+    it('refuses to export when references/ contains a symlink (blocks zip-dereference exfiltration)', () => {
+        // Simulate the exfiltration shape: a "secret" file living entirely
+        // outside srcDir, symlinked from within references/.
+        const secretsDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-pack-secret-'));
+        const secretPath = path_1.default.join(secretsDir, 'id_rsa');
+        const secretContents = 'THIS-IS-A-PRIVATE-KEY-SHOULD-NEVER-LEAK';
+        fs_1.default.writeFileSync(secretPath, secretContents);
+        fs_1.default.symlinkSync(secretPath, path_1.default.join(src, 'references/evil-link'));
+        try {
+            expect(() => (0, pack_1.packSkill)({ name: 'x', adaptedSkillMd: 'adapted', srcDir: src, targetRoot: out, zip: okZip })).toThrow(/symlink/i);
+            // Nothing under targetRoot should ever contain the secret's bytes,
+            // whether as a copied symlink or a dereferenced regular file.
+            const walk = (dir) => {
+                if (!fs_1.default.existsSync(dir))
+                    return [];
+                return fs_1.default.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+                    const full = path_1.default.join(dir, e.name);
+                    if (e.isDirectory())
+                        return walk(full);
+                    if (e.isSymbolicLink())
+                        return [full]; // leaked symlink itself is also unacceptable
+                    return [full];
+                });
+            };
+            for (const f of walk(out)) {
+                const st = fs_1.default.lstatSync(f);
+                if (st.isSymbolicLink()) {
+                    throw new Error(`leaked symlink found under targetRoot: ${f}`);
+                }
+                const contents = fs_1.default.readFileSync(f, 'utf-8');
+                expect(contents).not.toContain(secretContents);
+            }
+        }
+        finally {
+            fs_1.default.rmSync(secretsDir, { recursive: true, force: true });
+        }
+    });
+});
+describe('defaultZip (system binary, layered)', () => {
+    it('produces a real zip when the binary exists, or reports missing', () => {
+        const cwd = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-zip-'));
+        fs_1.default.mkdirSync(path_1.default.join(cwd, 'folder'));
+        fs_1.default.writeFileSync(path_1.default.join(cwd, 'folder/f.txt'), 'x');
+        const r = (0, pack_1.defaultZip)(cwd, 'folder.zip', 'folder');
+        if (r.missing) {
+            expect(fs_1.default.existsSync(path_1.default.join(cwd, 'folder.zip'))).toBe(false); // degrade limpio
+        }
+        else {
+            expect(r.ok).toBe(true);
+            expect(fs_1.default.existsSync(path_1.default.join(cwd, 'folder.zip'))).toBe(true);
+        }
+        fs_1.default.rmSync(cwd, { recursive: true, force: true });
+    });
+    it('returns missing:true when spawnSync reports ENOENT (binary absent)', () => {
+        const spy = jest.spyOn(childProcess, 'spawnSync').mockReturnValue({
+            error: Object.assign(new Error('spawn zip ENOENT'), { code: 'ENOENT' }),
+        });
+        const r = (0, pack_1.defaultZip)('/irrelevant', 'folder.zip', 'folder');
+        expect(r).toEqual({ ok: false, missing: true });
+        spy.mockRestore();
+    });
+});

package/dist/tests/core/export/resolve.test.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const resolve_1 = require("../../../src/core/export/resolve");
+/** Content root falso: catalog + bundle dev + 3 skills. */
+function makeRoot() {
+    const root = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-export-root-'));
+    fs_1.default.mkdirSync(path_1.default.join(root, 'bundles/dev'), { recursive: true });
+    fs_1.default.writeFileSync(path_1.default.join(root, 'catalog.json'), JSON.stringify({
+        version: 1,
+        bundles: [{ name: 'dev', source: './bundles/dev', version: '1.0.0', scope: 'baseline' }],
+    }));
+    fs_1.default.writeFileSync(path_1.default.join(root, 'bundles/dev/bundle.json'), JSON.stringify({
+        name: 'dev', version: '1.0.0', scope: 'baseline', dependsOn: [],
+        skills: ['proc-skill', { name: 'mermaid', onSignal: true }, { name: 'ported', onSignal: true }],
+        workflows: [], agents: [],
+    }));
+    const mk = (name, fm) => {
+        const dir = path_1.default.join(root, 'skills', name);
+        fs_1.default.mkdirSync(dir, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(dir, 'SKILL.md'), `---\n${fm.join('\n')}\n---\nBody.\n`);
+        return dir;
+    };
+    mk('proc-skill', ['name: proc-skill', 'description: "Process skill."']); // NO portable
+    mk('mermaid', ['name: mermaid', 'portable: true', 'description: "Diagrams."']);
+    const ported = mk('ported', ['name: ported', 'portable: true', 'description: "Ported."']);
+    fs_1.default.writeFileSync(path_1.default.join(ported, 'port.claude-ai.md'), '---\nname: ported\ndescription: "Custom."\n---\nCustom body.\n');
+    return root;
+}
+describe('resolveExport', () => {
+    let root;
+    beforeEach(() => { root = makeRoot(); });
+    afterEach(() => { fs_1.default.rmSync(root, { recursive: true, force: true }); });
+    it('resolves a bundle: portable skills in, non-portable listed as skipped', () => {
+        const res = (0, resolve_1.resolveExport)('dev', [root]);
+        expect(res.kind).toBe('bundle');
+        expect(res.skills.map((s) => s.name).sort()).toEqual(['mermaid', 'ported']);
+        expect(res.skipped).toEqual(['proc-skill']);
+    });
+    it('detects the override path when present', () => {
+        const res = (0, resolve_1.resolveExport)('dev', [root]);
+        const ported = res.skills.find((s) => s.name === 'ported');
+        expect(ported.overridePath).toBe(path_1.default.join(root, 'skills/ported/port.claude-ai.md'));
+        const mermaid = res.skills.find((s) => s.name === 'mermaid');
+        expect(mermaid.overridePath).toBeNull();
+    });
+    it('resolves an individual portable skill', () => {
+        const res = (0, resolve_1.resolveExport)('mermaid', [root]);
+        expect(res.kind).toBe('skill');
+        expect(res.skills).toHaveLength(1);
+        expect(res.skipped).toEqual([]);
+    });
+    it('fails on an explicitly requested non-portable skill', () => {
+        expect(() => (0, resolve_1.resolveExport)('proc-skill', [root])).toThrow(/portable/);
+    });
+    it('fails on unknown name, listing available bundles', () => {
+        expect(() => (0, resolve_1.resolveExport)('nope', [root])).toThrow(/dev/);
+    });
+    it('fails when a bundle has zero portable skills', () => {
+        fs_1.default.writeFileSync(path_1.default.join(root, 'skills/mermaid/SKILL.md'), '---\nname: mermaid\ndescription: "D."\n---\nB.\n');
+        fs_1.default.writeFileSync(path_1.default.join(root, 'skills/ported/SKILL.md'), '---\nname: ported\ndescription: "P."\n---\nB.\n');
+        fs_1.default.rmSync(path_1.default.join(root, 'skills/ported/port.claude-ai.md'));
+        expect(() => (0, resolve_1.resolveExport)('dev', [root])).toThrow(/no portable skills/i);
+    });
+    it('fails on override without portable: true (inconsistent metadata)', () => {
+        fs_1.default.writeFileSync(path_1.default.join(root, 'skills/ported/SKILL.md'), '---\nname: ported\ndescription: "P."\n---\nB.\n');
+        expect(() => (0, resolve_1.resolveExport)('ported', [root])).toThrow(/inconsistent/i);
+    });
+    it('fails on override without portable: true when resolved via a bundle (assertOverrideConsistency bundle-loop path)', () => {
+        fs_1.default.writeFileSync(path_1.default.join(root, 'skills/ported/SKILL.md'), '---\nname: ported\ndescription: "P."\n---\nB.\n');
+        expect(() => (0, resolve_1.resolveExport)('dev', [root])).toThrow(/inconsistent/i);
+    });
+});

package/dist/tests/core/export/transform.test.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const transform_1 = require("../../../src/core/export/transform");
+const FM = (lines) => `---\n${lines.join('\n')}\n---\nBody line.\n`;
+describe('claudeAiTransform', () => {
+    it('strips version and portable, keeps other keys and body intact', () => {
+        const input = FM(['name: mermaid-diagrams', 'version: "1.0.0"', 'portable: true', 'description: "Guide."']);
+        const out = (0, transform_1.claudeAiTransform)(input, 'mermaid-diagrams');
+        expect(out).not.toMatch(/^version:/m);
+        expect(out).not.toMatch(/^portable:/m);
+        expect(out).toMatch(/^name: mermaid-diagrams$/m);
+        expect(out).toContain('Body line.\n');
+    });
+    it('appends the deference line inside a quoted description', () => {
+        const input = FM(['name: x', 'portable: true', 'description: "Does things."']);
+        const out = (0, transform_1.claudeAiTransform)(input, 'x');
+        expect(out).toContain(`description: "Does things. ${(0, transform_1.DEFERENCE_LINE)('x')}"`);
+    });
+    it('appends the deference line to an unquoted description', () => {
+        const input = FM(['name: x', 'portable: true', 'description: Does things.']);
+        const out = (0, transform_1.claudeAiTransform)(input, 'x');
+        expect(out).toContain(`description: Does things. ${(0, transform_1.DEFERENCE_LINE)('x')}`);
+    });
+    it('appends the deference line inside a single-quoted description', () => {
+        const input = FM(['name: x', 'portable: true', "description: 'Does things.'"]);
+        const out = (0, transform_1.claudeAiTransform)(input, 'x');
+        // DEFERENCE_LINE itself always contains an apostrophe ("registry's"), so
+        // even a fixture with no apostrophe of its own must see it doubled ('')
+        // per YAML single-quote escaping once spliced into a single-quoted scalar.
+        expect(out).toContain(`description: 'Does things. ${(0, transform_1.DEFERENCE_LINE)('x').replace(/'/g, "''")}'`);
+    });
+    it('appends the deference line inside a double-quoted description with trailing whitespace', () => {
+        const input = FM(['name: x', 'portable: true', 'description: "Does things."   ']);
+        const out = (0, transform_1.claudeAiTransform)(input, 'x');
+        expect(out).toContain(`description: "Does things. ${(0, transform_1.DEFERENCE_LINE)('x')}"`);
+    });
+    it('accepts CRLF-terminated frontmatter', () => {
+        const input = '---\r\nname: x\r\nportable: true\r\ndescription: "Does things."\r\n---\r\nBody line.\r\n';
+        const out = (0, transform_1.claudeAiTransform)(input, 'x');
+        expect(out).not.toMatch(/^portable:/m);
+        expect(out).toContain(`description: "Does things. ${(0, transform_1.DEFERENCE_LINE)('x')}"`);
+        expect(out).toContain('Body line.\r\n');
+    });
+    it('throws on missing frontmatter block', () => {
+        expect(() => (0, transform_1.claudeAiTransform)('No frontmatter here.', 'x')).toThrow(/frontmatter/);
+    });
+    it('throws on unterminated frontmatter block', () => {
+        expect(() => (0, transform_1.claudeAiTransform)('---\nname: x\ndescription: "D."\n', 'x')).toThrow(/unterminated/);
+    });
+    it('throws on frontmatter without description', () => {
+        expect(() => (0, transform_1.claudeAiTransform)(FM(['name: x', 'portable: true']), 'x')).toThrow(/description/);
+    });
+    it('throws on multi-line (block scalar) description', () => {
+        expect(() => (0, transform_1.claudeAiTransform)(FM(['name: x', 'description: >', '  folded text']), 'x')).toThrow(/single-line/);
+    });
+    it('escapes an apostrophe in the deference line when appending to a single-quoted description', () => {
+        const input = FM(['name: mermaid', 'portable: true', "description: 'Diagrams and flowcharts.'"]);
+        const out = (0, transform_1.claudeAiTransform)(input, 'mermaid');
+        // The apostrophe in "registry's" must be doubled ('') per YAML single-quote escaping.
+        expect(out).toContain("registry''s mermaid skill");
+        expect(out).not.toContain("registry's mermaid skill");
+        const descLine = out.split('\n').find((l) => l.startsWith('description:'));
+        expect(descLine).toBe(`description: 'Diagrams and flowcharts. ${(0, transform_1.DEFERENCE_LINE)('mermaid').replace(/'/g, "''")}'`);
+        // Sanity check the result is well-formed: single-quoted scalar body has no
+        // lone (unescaped) apostrophes — every ' is either the opening/closing
+        // quote or part of a doubled '' pair.
+        const body = descLine.slice('description: \''.length, -1);
+        expect(body.replace(/''/g, '')).not.toMatch(/'/);
+    });
+    it('throws when a quoted description has trailing content after its closing quote (e.g. inline comment)', () => {
+        const input = FM(['name: x', 'portable: true', 'description: "Does things." # a comment']);
+        expect(() => (0, transform_1.claudeAiTransform)(input, 'x')).toThrow(/trailing content|comment/i);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-workflow-manager",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "main": "dist/src/index.js",
   "bin": {
     "awm": "./dist/src/index.js"