@aiwg/cli 2026.10.11 → 2026.10.12

package/dist/src/skills/provider-extensions.js

@@ -0,0 +1,41 @@
+// Classify Claude-native fields separately from portable Agent Skills metadata.
+import { AIWG_SKILL_CONTROL_FIELDS, STANDARD_SKILL_FIELDS, } from './agent-skills.js';
+export const CLAUDE_SKILL_FIELDS = [
+    'disable-model-invocation', 'user-invocable', 'disallowed-tools', 'context',
+    'agent', 'background', 'model', 'effort', 'paths', 'shell', 'argument-hint',
+    'arguments',
+];
+export function agentSkillDocument(frontmatter, body) {
+    const standard = Object.fromEntries(STANDARD_SKILL_FIELDS
+        .filter((key) => Object.hasOwn(frontmatter, key))
+        .map((key) => [key, structuredClone(frontmatter[key])]));
+    const aiwg = Object.fromEntries(AIWG_SKILL_CONTROL_FIELDS
+        .filter((key) => Object.hasOwn(frontmatter, key))
+        .map((key) => [key, structuredClone(frontmatter[key])]));
+    const claude = Object.fromEntries(CLAUDE_SKILL_FIELDS
+        .filter((key) => Object.hasOwn(frontmatter, key))
+        .map((key) => [key, structuredClone(frontmatter[key])]));
+    const known = new Set([
+        ...STANDARD_SKILL_FIELDS, ...AIWG_SKILL_CONTROL_FIELDS, ...CLAUDE_SKILL_FIELDS,
+    ]);
+    return {
+        standard: standard,
+        aiwg,
+        ...(Object.keys(claude).length ? { providers: { claude } } : {}),
+        body,
+        resources: [],
+        unknownFields: Object.entries(frontmatter)
+            .filter(([key]) => !known.has(key))
+            .map(([key, value]) => ({ key, value: structuredClone(value) })),
+    };
+}
+/** Older sidecars retained context/effort under aiwg; preserve that spelling. */
+export function claudeSkillExtensions(document) {
+    return {
+        ...Object.fromEntries(CLAUDE_SKILL_FIELDS
+            .filter((key) => Object.hasOwn(document.aiwg, key))
+            .map((key) => [key, structuredClone(document.aiwg[key])])),
+        ...structuredClone(document.providers?.claude ?? {}),
+    };
+}
+//# sourceMappingURL=provider-extensions.js.map

package/dist/src/skills/run.js

@@ -159,6 +159,12 @@ export async function runSkill(opts) {
         ...(aiwgRoot ? { AIWG_ROOT: aiwgRoot } : {}),
         ...opts.env,
     };
+    // Native source owner shares the same indexed script declaration and project CWD.
+    if (entry.path.replaceAll('\\', '/').endsWith('agentic/code/frameworks/sdlc-complete/skills/issue-audit/SKILL.md')
+        && entry.script.entrypoint === 'scripts/audit.mjs') {
+        const audit = await import('../issues/audit-cli.js');
+        return audit.main(opts.args, runCwd, { env });
+    }
     const fullArgs = [...invocation.prefixArgs, entrypointPath, ...opts.args];
     return new Promise((resolve) => {
         const child = spawn(invocation.command, fullArgs, {

package/dist/src/skills/types.js

@@ -1,10 +1,2 @@
-/**
- * Skills Registry Types
- *
- * Defines the RegistryAdapter interface and result types for
- * provider-agnostic skill search, install, and publish operations.
- *
- * @implements #539
- */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/src/skills/validator-resources.js

@@ -0,0 +1,68 @@
+// Diagnose bundled skill resource references without changing parser policy.
+import fs from 'node:fs';
+import path from 'node:path';
+import { AGENT_SKILLS_BASELINE } from './agent-skills.js';
+const MARKDOWN_LINK = /!?\[[^\]]*]\(\s*(?:<([^>]+)>|([^\s)]+))(?:\s+["'][^)]*["'])?\s*\)/g;
+function diagnostic(code, severity, file, yamlPath, message, remediation) {
+    return {
+        code,
+        severity,
+        file,
+        yamlPath,
+        message,
+        upstreamBaseline: AGENT_SKILLS_BASELINE.revision,
+        remediation,
+    };
+}
+export function resourceDiagnostics(content, file, skillRoot, checkResources) {
+    const diagnostics = [];
+    const references = new Set();
+    for (const match of content.matchAll(MARKDOWN_LINK)) {
+        const raw = (match[1] ?? match[2] ?? '').trim();
+        if (raw.length === 0
+            || raw.startsWith('#')
+            || /^(?:https?|mailto|data):/i.test(raw)) {
+            continue;
+        }
+        const withoutFragment = raw.split('#', 1)[0] ?? '';
+        const decoded = (() => {
+            try {
+                return decodeURIComponent(withoutFragment);
+            }
+            catch {
+                return withoutFragment;
+            }
+        })();
+        references.add(decoded);
+    }
+    for (const reference of [...references].sort()) {
+        const normalized = reference.replaceAll('\\', '/');
+        if (path.isAbsolute(reference)
+            || normalized === '..'
+            || normalized.startsWith('../')
+            || normalized.includes('/../')) {
+            diagnostics.push(diagnostic('AS_RESOURCE_PATH', 'warning', file, '$.body', `resource reference "${reference}" is not an in-skill relative path`, 'Reference a file relative to SKILL.md without parent traversal.'));
+            continue;
+        }
+        const segments = normalized.split('/').filter(Boolean);
+        if (segments.length > 2) {
+            diagnostics.push(diagnostic('AS_ADVISORY_RESOURCE_DEPTH', 'warning', file, '$.body', `resource reference "${reference}" is deeper than one resource-directory level`, 'Prefer resources such as references/topic.md, scripts/run.sh, or assets/example.json.'));
+        }
+        if (!checkResources || !skillRoot)
+            continue;
+        const resolved = path.resolve(skillRoot, reference);
+        const relative = path.relative(skillRoot, resolved);
+        if (relative.startsWith('..')
+            || path.isAbsolute(relative)
+            || !fs.existsSync(resolved)) {
+            diagnostics.push(diagnostic('AS_RESOURCE_MISSING', 'warning', file, '$.body', `referenced resource "${reference}" does not exist`, 'Add the referenced file or correct the relative resource path.'));
+            continue;
+        }
+        const stat = fs.lstatSync(resolved);
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            diagnostics.push(diagnostic('AS_RESOURCE_TYPE', 'warning', file, '$.body', `referenced resource "${reference}" is not a regular file`, 'Replace the reference target with an in-tree regular file.'));
+        }
+    }
+    return diagnostics;
+}
+//# sourceMappingURL=validator-resources.js.map

package/dist/src/skills/validator.js

@@ -10,11 +10,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseDocument } from 'yaml';
+import { resourceDiagnostics } from './validator-resources.js';
+import { CLAUDE_SKILL_FIELDS } from './provider-extensions.js';
 import { AGENT_SKILLS_BASELINE, AGENT_SKILL_VALIDATION_PROFILES, AIWG_SKILL_CONTROL_FIELDS, STANDARD_SKILL_FIELDS, validateCompatibleAgentSkillMetadata, } from './agent-skills.js';
 const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
-const MARKDOWN_LINK = /!?\[[^\]]*]\(\s*(?:<([^>]+)>|([^\s)]+))(?:\s+["'][^)]*["'])?\s*\)/g;
 const STANDARD_FIELDS = new Set(STANDARD_SKILL_FIELDS);
 const AIWG_FIELDS = new Set(AIWG_SKILL_CONTROL_FIELDS);
+const CLAUDE_FIELDS = new Set(CLAUDE_SKILL_FIELDS);
 function diagnostic(code, severity, file, yamlPath, message, remediation) {
     return {
         code,
@@ -49,64 +51,13 @@ function normalizeMetadataDiagnostics(diagnostics, frontmatter, profile, file) {
     });
     if (!policy.recognizedAiwgFields) {
         for (const key of Object.keys(frontmatter).sort()) {
-            if (!AIWG_FIELDS.has(key))
+            if (!AIWG_FIELDS.has(key) && !CLAUDE_FIELDS.has(key))
                 continue;
-            normalized.push(diagnostic('AS_FIELD_EXTENSION', 'error', file, `$.${key}`, `AIWG extension field "${key}" is not allowed by the strict profile`, 'Remove the extension field or validate with the compatible profile.'));
+            normalized.push(diagnostic('AS_FIELD_EXTENSION', 'error', file, `$.${key}`, `Provider or AIWG extension field "${key}" is not allowed by the strict profile`, 'Remove the extension field or validate with the compatible profile.'));
         }
     }
     return normalized;
 }
-function resourceDiagnostics(content, file, skillRoot, checkResources) {
-    const diagnostics = [];
-    const references = new Set();
-    for (const match of content.matchAll(MARKDOWN_LINK)) {
-        const raw = (match[1] ?? match[2] ?? '').trim();
-        if (raw.length === 0
-            || raw.startsWith('#')
-            || /^(?:https?|mailto|data):/i.test(raw)) {
-            continue;
-        }
-        const withoutFragment = raw.split('#', 1)[0] ?? '';
-        const decoded = (() => {
-            try {
-                return decodeURIComponent(withoutFragment);
-            }
-            catch {
-                return withoutFragment;
-            }
-        })();
-        references.add(decoded);
-    }
-    for (const reference of [...references].sort()) {
-        const normalized = reference.replaceAll('\\', '/');
-        if (path.isAbsolute(reference)
-            || normalized === '..'
-            || normalized.startsWith('../')
-            || normalized.includes('/../')) {
-            diagnostics.push(diagnostic('AS_RESOURCE_PATH', 'warning', file, '$.body', `resource reference "${reference}" is not an in-skill relative path`, 'Reference a file relative to SKILL.md without parent traversal.'));
-            continue;
-        }
-        const segments = normalized.split('/').filter(Boolean);
-        if (segments.length > 2) {
-            diagnostics.push(diagnostic('AS_ADVISORY_RESOURCE_DEPTH', 'warning', file, '$.body', `resource reference "${reference}" is deeper than one resource-directory level`, 'Prefer resources such as references/topic.md, scripts/run.sh, or assets/example.json.'));
-        }
-        if (!checkResources || !skillRoot)
-            continue;
-        const resolved = path.resolve(skillRoot, reference);
-        const relative = path.relative(skillRoot, resolved);
-        if (relative.startsWith('..')
-            || path.isAbsolute(relative)
-            || !fs.existsSync(resolved)) {
-            diagnostics.push(diagnostic('AS_RESOURCE_MISSING', 'warning', file, '$.body', `referenced resource "${reference}" does not exist`, 'Add the referenced file or correct the relative resource path.'));
-            continue;
-        }
-        const stat = fs.lstatSync(resolved);
-        if (stat.isSymbolicLink() || !stat.isFile()) {
-            diagnostics.push(diagnostic('AS_RESOURCE_TYPE', 'warning', file, '$.body', `referenced resource "${reference}" is not a regular file`, 'Replace the reference target with an in-tree regular file.'));
-        }
-    }
-    return diagnostics;
-}
 function resultState(diagnostics, profile) {
     const errors = diagnostics.filter((item) => item.severity === 'error');
     if (errors.length > 0) {
@@ -213,7 +164,7 @@ export function validateAgentSkillContent(content, options = {}) {
     // Defensive policy check: a future field added to one allow-list must not
     // silently escape classification in this parser.
     for (const key of Object.keys(frontmatter).sort()) {
-        if (STANDARD_FIELDS.has(key) || AIWG_FIELDS.has(key))
+        if (STANDARD_FIELDS.has(key) || AIWG_FIELDS.has(key) || CLAUDE_FIELDS.has(key))
             continue;
         if (!diagnostics.some((item) => item.yamlPath === `$.${key}`)) {
             diagnostics.push(diagnostic('AS_FIELD_UNKNOWN', AGENT_SKILL_VALIDATION_PROFILES[profile].unknownField, file, `$.${key}`, `unrecognized top-level field "${key}"`, 'Remove the field or map it explicitly before granting it policy meaning.'));

package/dist/src/storage/cli-migrate-options.js

@@ -0,0 +1,125 @@
+// Parses migration flags and resolves existing storage adapters.
+import { join, resolve as resolvePath } from 'node:path';
+import { BACKEND_TYPES, SUBSYSTEM_KEYS, FilesystemAdapter, ObsidianAdapter, LogseqAdapter, FortemiAdapter, } from './index.js';
+export function parseMigrateArgs(args) {
+    let subsystem;
+    let from;
+    let to;
+    let fromFolder;
+    let toFolder;
+    let dryRun = false;
+    let textOnly = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--from')
+            from = args[++i];
+        else if (a === '--to')
+            to = args[++i];
+        else if (a === '--from-folder')
+            fromFolder = args[++i];
+        else if (a === '--to-folder')
+            toFolder = args[++i];
+        else if (a === '--dry-run')
+            dryRun = true;
+        else if (a === '--text-only')
+            textOnly = true;
+        else if (!a.startsWith('--') && !subsystem)
+            subsystem = a;
+        else
+            throw new Error(`Unknown migrate flag: ${a}`);
+    }
+    if (!subsystem || !SUBSYSTEM_KEYS.includes(subsystem)) {
+        throw new Error(`Usage: aiwg storage migrate <subsystem> --from <type>:<location> --to <type>:<location> [--dry-run]\n  Valid subsystems: ${SUBSYSTEM_KEYS.join(', ')}`);
+    }
+    if (!from)
+        throw new Error('storage migrate: --from <type>:<location> is required');
+    if (!to)
+        throw new Error('storage migrate: --to <type>:<location> is required');
+    return {
+        subsystem: subsystem,
+        from: { ...parseSpec(from), ...(fromFolder ? { folder: fromFolder } : {}) },
+        to: { ...parseSpec(to), ...(toFolder ? { folder: toFolder } : {}) },
+        dryRun,
+        textOnly,
+    };
+}
+export function parseSpec(raw) {
+    const idx = raw.indexOf(':');
+    if (idx === -1) {
+        throw new Error(`Invalid backend spec "${raw}" — expected <type>:<location>`);
+    }
+    const type = raw.slice(0, idx);
+    const location = raw.slice(idx + 1);
+    if (!BACKEND_TYPES.includes(type)) {
+        throw new Error(`Unknown backend type "${type}" in spec "${raw}". Valid: ${BACKEND_TYPES.join(', ')}`);
+    }
+    if (location.length === 0) {
+        throw new Error(`Empty location in backend spec "${raw}"`);
+    }
+    return { type: type, location };
+}
+export function buildAdapter(subsystem, spec, projectRoot) {
+    switch (spec.type) {
+        case 'fs': {
+            const root = expandFsLocation(spec.location, projectRoot);
+            return new FilesystemAdapter(root);
+        }
+        case 'obsidian':
+            return new ObsidianAdapter({
+                type: 'obsidian',
+                vault: expandFsLocation(spec.location, projectRoot),
+                ...(spec.folder ? { folder: spec.folder } : {}),
+                useCli: false,
+            });
+        case 'logseq':
+            return new LogseqAdapter({
+                type: 'logseq',
+                graph: expandFsLocation(spec.location, projectRoot),
+                useApi: false,
+            });
+        case 'fortemi':
+            return new FortemiAdapter({
+                subsystem,
+                config: { type: 'fortemi', mcpServer: spec.location },
+            });
+        case 'notion':
+        case 'anythingllm':
+        case 's3':
+        case 'webdav':
+            throw new Error(`storage migrate: backend "${spec.type}" not yet implemented. ` +
+                `See issues #959, #960, #962, #963 for tracking.`);
+        default: {
+            const _exhaustive = spec.type;
+            void _exhaustive;
+            throw new Error(`Unhandled backend type ${spec.type}`);
+        }
+    }
+}
+export function expandFsLocation(loc, projectRoot) {
+    if (loc.startsWith('~/')) {
+        const { homedir } = require('os');
+        return join(homedir(), loc.slice(2));
+    }
+    if (loc === '~') {
+        const { homedir } = require('os');
+        return homedir();
+    }
+    if (loc.startsWith('/'))
+        return loc;
+    return resolvePath(projectRoot, loc);
+}
+export function locationsEqual(a, b, projectRoot) {
+    if (a.type !== b.type)
+        return false;
+    if (a.type === 'fortemi')
+        return a.location === b.location;
+    // For file-shaped backends, compare resolved fs paths
+    return expandFsLocation(a.location, projectRoot) === expandFsLocation(b.location, projectRoot);
+}
+export function describeSpec(spec) {
+    return spec.folder ? `${spec.type}:${spec.location} (folder=${spec.folder})` : `${spec.type}:${spec.location}`;
+}
+export function specSlug(spec) {
+    return `${spec.type}-${spec.location.replace(/[^a-zA-Z0-9]/g, '_').slice(0, 32)}`;
+}
+//# sourceMappingURL=cli-migrate-options.js.map

package/dist/src/storage/cli-migrate.js

@@ -0,0 +1,111 @@
+// Runs storage migrate through the protocol copy coordinator and preserves CLI output.
+import { randomUUID } from 'node:crypto';
+import { appendFile, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { projectAiwgPath } from '../config/project-artifacts.js';
+import { STORAGE_MIGRATION_PROTOCOL, StorageMigrationCoordinator } from './migration-protocol.js';
+import { isTextCorpusEntry, migrationEndpoint } from './migration-adapter.js';
+import { sha256, stableStringify } from './migration-records.js';
+import { buildAdapter, describeSpec, expandFsLocation, locationsEqual, parseMigrateArgs, specSlug, } from './cli-migrate-options.js';
+export async function handleMigrate(projectRoot, args) {
+    const opts = parseMigrateArgs(args);
+    if (locationsEqual(opts.from, opts.to, projectRoot)) {
+        throw new Error(`Refusing to migrate: source and destination resolve to the same location.\n  ${describeSpec(opts.from)}\n  ${describeSpec(opts.to)}`);
+    }
+    const source = buildAdapter(opts.subsystem, opts.from, projectRoot);
+    const destination = buildAdapter(opts.subsystem, opts.to, projectRoot);
+    const identity = (spec) => ({
+        backend: spec.type, instance: stableStringify({
+            location: spec.type === 'fortemi' ? spec.location : expandFsLocation(spec.location, projectRoot),
+            folder: spec.folder ?? '',
+        }), tenant: projectRoot, subsystem: opts.subsystem, schemaVersion: '1',
+    });
+    const sourceEndpoint = migrationEndpoint(source, identity(opts.from));
+    const destinationEndpoint = migrationEndpoint(destination, identity(opts.to));
+    const migrationLogPath = projectAiwgPath(projectRoot, '.storage-cache', 'migrations', `${opts.subsystem}-${specSlug(opts.from)}-to-${specSlug(opts.to)}.jsonl`);
+    // Bind checkpoint filenames to full, resolved identities, folders and selection policy.
+    const binding = sha256(stableStringify([sourceEndpoint.identity, destinationEndpoint.identity, opts.textOnly]));
+    const checkpointPath = `${migrationLogPath}.${binding}.checkpoint.json`;
+    const receiptPath = `${checkpointPath}.receipt.json`;
+    try {
+        if (source.init)
+            await source.init();
+        if (!opts.dryRun && destination.init)
+            await destination.init();
+        console.log(`storage migrate (${opts.dryRun ? 'DRY RUN' : 'live'})`);
+        console.log(`  subsystem: ${opts.subsystem}`);
+        console.log(`  from:      ${describeSpec(opts.from)}`);
+        console.log(`  to:        ${describeSpec(opts.to)}`);
+        console.log('');
+        const checkpoint = await loadCheckpoint(checkpointPath);
+        const result = await StorageMigrationCoordinator.copy({
+            source: sourceEndpoint, destination: destinationEndpoint, checkpoint, dryRun: opts.dryRun,
+            exclude: path => opts.textOnly && !isTextCorpusEntry(path) ? 'non-text attachment skipped' : undefined,
+            async save(value) {
+                await atomicJson(checkpointPath, value);
+                await atomicJson(receiptPath, { protocol: value.protocol, migrationId: value.migrationId, ...value.receipt });
+            },
+            async report(action, item) {
+                if (action === 'errored')
+                    console.log(`  ✗ ${item.path} (${item.reason})`);
+                else if (action === 'skipped') {
+                    const marker = item.reason === 'already migrated, skipped' ? '✓' : '·';
+                    console.log(`  ${marker} ${item.path} (${item.reason})`);
+                }
+                else if (opts.dryRun) {
+                    console.log(`  → ${item.path} (would ${action === 'deleted' ? 'delete' : 'copy'})`);
+                }
+                else {
+                    console.log(`  ✓ ${item.path}${action === 'copied' ? '' : ` (${action}: ${item.reason})`}`);
+                    await mkdir(dirname(migrationLogPath), { recursive: true });
+                    await appendFile(migrationLogPath, JSON.stringify({
+                        path: item.path, ts: new Date().toISOString(), action, reason: item.reason, protocol: STORAGE_MIGRATION_PROTOCOL,
+                    }) + '\n', 'utf-8');
+                }
+            },
+        });
+        const receipt = result.receipt;
+        const unsupported = receipt.skipped.filter(item => item.reason === 'non-text attachment skipped').length;
+        const copied = receipt.copied.length + receipt.recopied.length;
+        const skipped = receipt.skipped.length - unsupported;
+        if (!result.plan.length)
+            console.log('No entries to migrate.');
+        console.log('');
+        console.log(`Summary: copied=${copied} skipped=${skipped} unsupported=${unsupported} ` +
+            `errored=${receipt.errored.length} total=${result.plan.length} ` +
+            `recopied=${receipt.recopied.length} deleted=${receipt.deleted.length}`);
+        if (!opts.dryRun) {
+            console.log(`Migration log: ${migrationLogPath}`);
+            console.log(`Migration checkpoint: ${checkpointPath}`);
+            console.log(`Migration receipt: ${receiptPath}`);
+        }
+        if (receipt.errored.length) {
+            throw new Error(`${receipt.errored.length} entr${receipt.errored.length === 1 ? 'y' : 'ies'} failed to migrate.`);
+        }
+    }
+    finally {
+        await Promise.allSettled([source.close?.(), destination.close?.()]);
+    }
+}
+async function loadCheckpoint(path) {
+    try {
+        return JSON.parse(await readFile(path, 'utf-8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+async function atomicJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(value, null, 2) + '\n', 'utf-8');
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+//# sourceMappingURL=cli-migrate.js.map