aiwf 0.3.23 → 0.4.0

package/scripts/install-spec-skills.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const plugins = resolve(dirname(fileURLToPath(import.meta.url)), '../plugins');
+export const supportedStacks = ['vaadin-jooq', 'angular-jpa', 'blazor-dotnet', 'nestjs-nextjs'];
+export const supportedDelegates = ['claude', 'codex'];
+
+function markdownFiles(directory) {
+  return readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const file = join(directory, entry.name);
+    return entry.isDirectory() ? markdownFiles(file) : entry.name.endsWith('.md') ? [file] : [];
+  });
+}
+
+function rejectSymlink(path) {
+  if (existsSync(path) && lstatSync(path).isSymbolicLink()) {
+    throw new Error(`Refusing symbolic link: ${path}`);
+  }
+}
+
+export function installSpecSkills(project, { dryRun = false, stack, delegates = [] } = {}) {
+  if (stack !== undefined && !supportedStacks.includes(stack)) {
+    throw new Error(`Unknown stack: ${stack}; choose ${supportedStacks.join(', ')}`);
+  }
+  if (!Array.isArray(delegates) || delegates.some(target => !supportedDelegates.includes(target))) {
+    throw new Error(`Unknown delegate: choose ${supportedDelegates.join(', ')}`);
+  }
+  delegates = [...new Set(delegates)];
+  const root = resolve(project);
+  rejectSymlink(root);
+  if (!existsSync(root) || !lstatSync(root).isDirectory()) {
+    throw new Error(`Project directory does not exist: ${root}`);
+  }
+  const target = join(root, '.agents', 'skills');
+  for (const path of [join(root, '.agents'), target]) {
+    rejectSymlink(path);
+    if (existsSync(path) && !lstatSync(path).isDirectory()) {
+      throw new Error(`Expected directory: ${path}`);
+    }
+  }
+  const bundles = [
+    { plugin: join(plugins, 'aiwf-core'), prefix: 'aiwf-' },
+    { plugin: join(plugins, 'aiwf-spec'), prefix: 'aiwf-' }
+  ];
+  if (stack) { bundles.push({ plugin: join(plugins, `aiwf-${stack}`), prefix: `aiwf-${stack}-` }); }
+  for (const target of delegates) {
+    bundles.push({ plugin: join(plugins, `aiwf-delegate-${target}`), prefix: 'aiwf-' });
+  }
+  const entries = bundles.flatMap(bundle => readdirSync(join(bundle.plugin, 'skills')).sort()
+    .map(name => ({ ...bundle, name, installedName: `${bundle.prefix}${name}` })));
+  const destinations = entries.map(entry => join(target, entry.installedName));
+  for (const destination of destinations) {
+    // lstat detects dangling symlinks too.
+    try {
+      lstatSync(destination);
+      throw new Error(`Skill already exists; no files overwritten: ${destination}`);
+    } catch (error) {
+      if (error.code !== 'ENOENT') { throw error; }
+    }
+  }
+  if (dryRun) { return { dry_run: true, destinations }; }
+  mkdirSync(target, { recursive: true });
+  for (let index = 0; index < entries.length; index++) {
+    const entry = entries[index];
+    const destination = destinations[index];
+    cpSync(join(entry.plugin, 'skills', entry.name), destination, { recursive: true, errorOnExist: true, force: false });
+    for (const notice of ['LICENSE', 'NOTICE']) { cpSync(join(entry.plugin, notice), join(destination, notice)); }
+    for (const resources of ['rules', 'agents']) {
+      if (existsSync(join(entry.plugin, resources))) {
+        cpSync(join(entry.plugin, resources), join(destination, resources), { recursive: true, errorOnExist: true, force: false });
+      }
+    }
+    // Stack-local names take precedence; shared core commands retain their core names.
+    const mapping = new Map(entries.filter(item => item.prefix === 'aiwf-').map(item => [item.name, item.installedName]));
+    for (const item of entries.filter(item => item.plugin === entry.plugin)) {
+      mapping.set(item.name, item.installedName);
+    }
+    const commands = new RegExp(`(?<![.\\w-])/(${[...mapping.keys()].join('|')})(?![\\w-])`, 'g');
+    const namedSkills = new RegExp('`(' + [...mapping.keys()].join('|') + ')`', 'g');
+    for (const file of markdownFiles(destination)) {
+      const original = readFileSync(file, 'utf8');
+      let text = original;
+      if (file === join(destination, 'SKILL.md')) {
+        text = text.replace(/^name: .+$/m, `name: ${entry.installedName}`);
+      }
+      text = text.replace(commands, (_, name) => `/${mapping.get(name)}`)
+        .replace(namedSkills, (_, name) => '`' + mapping.get(name) + '`');
+      if (text !== original) {
+        text += '\n<!-- AIWF installation modification: prefixed skill names and command references throughout bundled Markdown. -->\n';
+        writeFileSync(file, text);
+      }
+    }
+  }
+  return { dry_run: false, installed: destinations };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try {
+    const args = process.argv.slice(2);
+    let project;
+    let dryRun = false;
+    let stack;
+    const delegates = [];
+    for (let index = 0; index < args.length; index++) {
+      if (args[index] === '--project' && args[index + 1] && !args[index + 1].startsWith('--') && !project) {
+        project = args[++index];
+      } else if (args[index] === '--dry-run' && !dryRun) {
+        dryRun = true;
+      } else if (args[index] === '--stack' && args[index + 1] && !args[index + 1].startsWith('--') && !stack) {
+        stack = args[++index];
+      } else if (args[index] === '--delegate' && args[index + 1] && !args[index + 1].startsWith('--')) {
+        delegates.push(args[++index]);
+      } else if (args[index] === '--help') {
+        console.log(`node scripts/install-spec-skills.mjs --project <existing-project> [--stack <${supportedStacks.join('|')}>] [--delegate <${supportedDelegates.join('|')}> ...] [--dry-run]`);
+        process.exit(0);
+      } else { throw new Error(`Unknown or incomplete argument: ${args[index]}`); }
+    }
+    if (!project) { throw new Error('--project is required'); }
+    console.log(JSON.stringify(installSpecSkills(project, { dryRun, stack, delegates }), null, 2));
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/scripts/validate-spec-plugin.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { supportedStacks } from './install-spec-skills.mjs';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const read = path => readFileSync(path, 'utf8');
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+const market = JSON.parse(read(join(root, '.claude-plugin/marketplace.json')));
+const pkg = JSON.parse(read(join(root, 'package.json')));
+let verified = 0;
+let modified = 0;
+let skills = 0;
+let importedSkills = 0;
+let commit;
+
+// AIWF-owned skill directories in aiwf-spec are authored here, not imported, so they
+// carry no upstream provenance. Keep this list narrow: only the named skill roots are
+// exempt, never arbitrary untracked resources in the plugin.
+const aiwfOwnedSkillRoots = ['skills/workflow/', 'skills/sync-docs/'];
+const isAiwfOwned = relative => aiwfOwnedSkillRoots.some(directory => relative.startsWith(directory));
+
+function files(directory) {
+  return readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const file = join(directory, entry.name);
+    return entry.isDirectory() ? files(file) : [file];
+  });
+}
+
+for (const name of ['aiwf-core', 'aiwf-spec', ...supportedStacks.map(stack => `aiwf-${stack}`)]) {
+  const plugin = join(root, 'plugins', name);
+  const provenance = name === 'aiwf-spec' ? { upstream_sha256: {}, modified_sha256: {} }
+    : JSON.parse(read(join(plugin, 'UPSTREAM.json')));
+  if (name !== 'aiwf-spec') {
+    assert.equal(provenance.repository, 'https://github.com/AI-Unified-Process/marketplace');
+    assert.match(provenance.commit, /^[0-9a-f]{40}$/);
+    commit ??= provenance.commit;
+    assert.equal(provenance.commit, commit, `Mixed upstream versions: ${name}`);
+  }
+  const allowedModifications = name === 'aiwf-core' ? ['NOTICE'] : [];
+  for (const [path, expected] of Object.entries(provenance.modified_sha256)) {
+    assert.ok(allowedModifications.includes(path), `Upstream sources must stay unchanged: ${name}/${path}`);
+    assert.equal(digest(readFileSync(join(plugin, path))), expected, `Modified resource changed: ${name}/${path}`);
+    modified++;
+  }
+  for (const [path, expected] of Object.entries(provenance.upstream_sha256)) {
+    const bytes = readFileSync(join(plugin, path));
+    if (Object.hasOwn(provenance.modified_sha256, path)) {
+      assert.equal(path, 'NOTICE');
+      assert.match(bytes.toString(), /derived from the AI Unified Process Marketplace by Simon Martinelli/);
+    } else {
+      assert.equal(digest(bytes), expected, `Upstream resource changed: ${name}/${path}`);
+      verified++;
+    }
+    if (path.endsWith('/SKILL.md')) { importedSkills++; }
+  }
+  for (const directory of ['skills', 'rules', 'agents']) {
+    if (!existsSync(join(plugin, directory))) { continue; }
+    for (const file of files(join(plugin, directory))) {
+      const relative = file.slice(plugin.length + 1);
+      if (name === 'aiwf-spec' && isAiwfOwned(relative)) { continue; }
+      assert.ok(Object.hasOwn(provenance.upstream_sha256, relative), `Resource missing provenance: ${name}/${relative}`);
+    }
+  }
+  const names = readdirSync(join(plugin, 'skills')).sort();
+  if (name === 'aiwf-core') { assert.equal(names.length, 7); }
+  if (name === 'aiwf-spec') { assert.deepEqual(names, ['sync-docs', 'workflow']); }
+  skills += names.length;
+  for (const skill of names) {
+    const file = join(plugin, 'skills', skill, 'SKILL.md');
+    const text = read(file);
+    assert.match(text, new RegExp(`^---\\nname: ${skill}\\n`, 'm'), `Skill name mismatch: ${name}/${skill}`);
+    assert.match(text, /^description: .+/m);
+    assert.match(text, /Apache(-| License, Version )2\.0/);
+    for (const markdown of files(dirname(file)).filter(path => path.endsWith('.md'))) {
+      const prose = read(markdown).replace(/^```[^\n]*\n[\s\S]*?^```\s*$/gm, '');
+      for (const match of prose.matchAll(/\]\(([^\s)]+)\)/g)) {
+        const ref = match[1].split('#')[0];
+        // Project-artifact links in template examples are not bundled resources.
+        if (!/^(references|scripts)\//.test(ref)) { continue; }
+        assert.ok(existsSync(resolve(dirname(markdown), ref)), `Broken bundled reference: ${name}/${skill}: ${ref}`);
+      }
+    }
+  }
+  const entry = market.plugins.find(p => p.name === name);
+  assert.ok(entry, `Marketplace entry missing: ${name}`);
+  assert.equal(entry.source, `./plugins/${name}`);
+  const manifest = JSON.parse(read(join(plugin, '.claude-plugin/plugin.json')));
+  assert.equal(manifest.name, entry.name);
+  assert.equal(manifest.version, entry.version);
+  assert.ok(pkg.files.includes(`plugins/${name}/`), `Package excludes plugin: ${name}`);
+}
+assert.equal(importedSkills, 31);
+const delegationTargets = ['claude', 'codex'];
+for (const target of delegationTargets) {
+  const name = `aiwf-delegate-${target}`;
+  const plugin = join(root, 'plugins', name);
+  const expectedSkill = `delegate-${target}`;
+  assert.deepEqual(readdirSync(join(plugin, 'skills')), [expectedSkill]);
+  const skill = read(join(plugin, 'skills', expectedSkill, 'SKILL.md'));
+  assert.match(skill, new RegExp(`^name: ${expectedSkill}$`, 'm'));
+  assert.match(skill, /^disable-model-invocation: true$/m);
+  assert.match(read(join(plugin, 'skills', expectedSkill, 'agents/openai.yaml')), /allow_implicit_invocation: false/);
+  for (const requiredPolicy of [
+    /current user request contains the literal token `--cross-cli`/,
+    /does not consent to starting a separate CLI process/,
+    /For cross-CLI work, default to read-only/,
+    /explicitly asks for file changes, with the files or directory scope stated/,
+    /Native subagents follow the current host's normal permission policy/,
+    /If the native subagent tool is unavailable, report that route as unavailable and stop, even when `--cross-cli` is present/,
+    /Do not substitute this host's native agents, another provider, or do the task yourself/,
+    /Do not substitute `npx`, a bundled or renamed binary, or another provider's CLI/,
+    /same operating-system account and inherits the current working directory and environment/,
+    /not a security-isolation boundary/,
+    /Do not expose environment secrets in prompts or output/,
+    /instead of retrying through another tool, broader access, or `sudo`/
+  ]) {
+    assert.match(skill, requiredPolicy, `Missing delegation safety policy: ${name} ${requiredPolicy}`);
+  }
+  if (target === 'claude') {
+    assert.match(skill, /--permission-mode plan/);
+    assert.match(skill, /Never add `--dangerously-skip-permissions`/);
+  } else {
+    assert.match(skill, /Codex `exec` defaults to a read-only sandbox/);
+    assert.match(skill, /Add `--sandbox workspace-write` only if the current user request explicitly authorizes writes/);
+    assert.match(skill, /Never add `--full-auto`, `--danger-full-access`/);
+  }
+  const entry = market.plugins.find(item => item.name === name);
+  assert.ok(entry, `Marketplace entry missing: ${name}`);
+  assert.equal(entry.source, `./plugins/${name}`);
+  assert.equal(entry.version, '0.1.0');
+  for (const manifestPath of ['.claude-plugin/plugin.json', 'plugin.json']) {
+    const manifest = JSON.parse(read(join(plugin, manifestPath)));
+    assert.equal(manifest.name, name);
+    assert.equal(manifest.version, entry.version);
+  }
+  assert.ok(pkg.files.includes(`plugins/${name}/`), `Package excludes plugin: ${name}`);
+  skills++;
+}
+assert.equal(skills, 35);
+assert.equal(pkg.bin['aiwf-spec'], './src/cli/spec-cli.js');
+console.log(`AIWF: ${importedSkills} unchanged upstream skills + ${skills - importedSkills} AIWF skills (workflow, sync-docs and optional delegates); ${verified} unchanged upstream resources, ${modified} attributed NOTICE modification; references and manifests validated.`);

package/src/cli/spec-cli.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+
+/**
+ * aiwf-spec - bounded AIWF specification workflow CLI.
+ *
+ * Commands: init, pin, check, packet. Built-in Node modules only.
+ * This CLI records local snapshots and evidence; it never claims approval.
+ */
+
+import { existsSync, realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+import {
+  initSpec,
+  pinSpec,
+  checkSpec,
+  createReviewPacket,
+  writeReviewPacket
+} from '../lib/spec-workflow.js';
+
+const EXIT_OK = 0;
+const EXIT_FAILURE = 1;
+const EXIT_USAGE = 2;
+
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+    this.code = 'usage_error';
+  }
+}
+
+export const COMMANDS = {
+  init: {
+    summary: 'Create minimal Draft AIUP-compatible spec files (never overwrites).',
+    string: ['root', 'name'],
+    boolean: ['json'],
+    required: ['root', 'name']
+  },
+  pin: {
+    summary: 'Snapshot the spec into .aiwf/spec-pin.json.',
+    string: ['root'],
+    boolean: ['json', 'refresh'],
+    required: ['root']
+  },
+  check: {
+    summary: 'Compare the pinned spec against the current working tree (read-only).',
+    string: ['root'],
+    boolean: ['json'],
+    required: ['root']
+  },
+  packet: {
+    summary: 'Build a local review packet from a pinned spec and an evidence file.',
+    string: ['root', 'evidence', 'output'],
+    boolean: ['json', 'force'],
+    required: ['root', 'evidence']
+  }
+};
+
+function camel(key) {
+  return key.replace(/-([a-z])/g, (_, char) => char.toUpperCase());
+}
+
+/**
+ * Strict option parser: unknown options, missing values, and stray positionals are rejected.
+ */
+export function parseOptions(args, config) {
+  const options = {};
+  const positionals = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      let key = arg.slice(2);
+      let value;
+      const eq = key.indexOf('=');
+      if (eq !== -1) {
+        value = key.slice(eq + 1);
+        key = key.slice(0, eq);
+      }
+      const name = camel(key);
+      if (config.boolean.includes(name)) {
+        if (value !== undefined) {
+          throw new UsageError(`Option --${key} does not take a value.`);
+        }
+        options[name] = true;
+      } else if (config.string.includes(name)) {
+        if (value === undefined) {
+          value = args[i + 1];
+          i += 1;
+        }
+        if (value === undefined || value === '' || value.startsWith('--')) {
+          throw new UsageError(`Missing value for option --${key}.`);
+        }
+        options[name] = value;
+      } else {
+        throw new UsageError(`Unknown option: --${key}`);
+      }
+    } else if (arg.startsWith('-') && arg.length > 1) {
+      throw new UsageError(`Unknown option: ${arg}`);
+    } else {
+      positionals.push(arg);
+    }
+  }
+
+  if (positionals.length > 0) {
+    throw new UsageError(`Unexpected argument: ${positionals[0]}`);
+  }
+
+  return options;
+}
+
+function printHelp(stream = process.stdout) {
+  const lines = [
+    'aiwf-spec - bounded AIWF specification workflow',
+    '',
+    'Usage: aiwf-spec <command> [options]',
+    '',
+    'Commands:'
+  ];
+  for (const [name, config] of Object.entries(COMMANDS)) {
+    lines.push(`  ${name.padEnd(8)} ${config.summary}`);
+  }
+  lines.push(
+    '',
+    'Options:',
+    '  --root <path>        Project root directory (required for all commands).',
+    '  --name <title>       Product title for init.',
+    '  --evidence <file>    Evidence JSON file for packet.',
+    '  --output <path>      Packet output path (default .aiwf/review-packet.json).',
+    '  --refresh            Overwrite an existing, differing pin (pin).',
+    '  --force              Overwrite an existing review packet (packet).',
+    '  --json               Emit machine-readable JSON on stdout.',
+    '  -h, --help           Show this help.',
+    '',
+    'Notes:',
+    '  Snapshots cover docs/vision.md, requirements.md, glossary.md, entity_model.md,',
+    '  use_cases.puml, *.md under use_cases/test_cases/architecture/plans,',
+    '  *.bpmn under docs/processes, and docs/.spec-lint-baseline.json when present.',
+    '  Only unresolved TODO / NEEDS CLARIFICATION markers block pinning; Draft and',
+    '  Reviewed status words are recorded as written and are not approvals.',
+    '  Structural and semantic lint is not performed here; it remains an upstream step.',
+    '',
+    'Exit codes: 0 success, 1 spec/pin failure, 2 usage error.'
+  );
+  stream.write(`${lines.join('\n')}\n`);
+}
+
+function emitJson(payload) {
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function emitError(command, error, json) {
+  const code = error.code || 'error';
+  if (json) {
+    emitJson({ command, error: { code, message: error.message } });
+  } else {
+    process.stderr.write(`${code}: ${error.message}\n`);
+  }
+}
+
+function runInit(options) {
+  const result = initSpec(options.root, options.name);
+  if (options.json) {
+    return { code: EXIT_OK, payload: result };
+  }
+  process.stdout.write(
+    `Initialized spec at ${result.root}\nCreated: ${result.created.length}, preserved: ${result.preserved.length}\n`
+  );
+  return { code: EXIT_OK };
+}
+
+function runPin(options) {
+  const result = pinSpec(options.root, { refresh: Boolean(options.refresh) });
+  if (options.json) {
+    return { code: EXIT_OK, payload: result };
+  }
+  const verb = result.unchanged ? 'Pin unchanged' : 'Pinned';
+  process.stdout.write(`${verb} ${result.pin.files.length} files (digest ${result.digest}).\n`);
+  return { code: EXIT_OK };
+}
+
+function runCheck(options) {
+  const result = checkSpec(options.root);
+  const code = result.in_sync ? EXIT_OK : EXIT_FAILURE;
+  if (options.json) {
+    return { code, payload: result };
+  }
+  process.stdout.write(`status: ${result.status}\n`);
+  if (result.added.length > 0) {
+    process.stdout.write(`added: ${result.added.join(', ')}\n`);
+  }
+  if (result.changed.length > 0) {
+    process.stdout.write(`changed: ${result.changed.join(', ')}\n`);
+  }
+  if (result.deleted.length > 0) {
+    process.stdout.write(`deleted: ${result.deleted.join(', ')}\n`);
+  }
+  if (result.draft_markers.length > 0) {
+    process.stdout.write(`draft markers: ${result.draft_markers.map(m => m.path).join(', ')}\n`);
+  }
+  return { code };
+}
+
+function runPacket(options) {
+  const packet = createReviewPacket(options.root, options.evidence, { cwd: process.cwd() });
+  const written = writeReviewPacket(options.root, packet, {
+    output: options.output,
+    force: Boolean(options.force),
+    cwd: process.cwd()
+  });
+  if (options.json) {
+    return { code: EXIT_OK, payload: packet };
+  }
+  process.stdout.write(`Wrote review packet: ${written.output} (status: ${packet.status})\n`);
+  return { code: EXIT_OK };
+}
+
+const RUNNERS = {
+  init: runInit,
+  pin: runPin,
+  check: runCheck,
+  packet: runPacket
+};
+
+/**
+ * Execute the CLI. Returns the process exit code and writes all output.
+ */
+export function run(argv = process.argv.slice(2)) {
+  const [command, ...rest] = argv;
+
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    printHelp();
+    return EXIT_OK;
+  }
+
+  const config = COMMANDS[command];
+  if (!config) {
+    process.stderr.write(`Unknown command: ${command}\n`);
+    printHelp(process.stderr);
+    return EXIT_USAGE;
+  }
+
+  let options;
+  try {
+    options = parseOptions(rest, config);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    return EXIT_USAGE;
+  }
+
+  if (options.help) {
+    printHelp();
+    return EXIT_OK;
+  }
+
+  for (const required of config.required) {
+    if (options[required] === undefined) {
+      process.stderr.write(`Missing required option: --${required.replace(/[A-Z]/g, c => `-${c.toLowerCase()}`)}\n`);
+      return EXIT_USAGE;
+    }
+  }
+
+  try {
+    const result = RUNNERS[command](options);
+    if (result.payload !== undefined) {
+      emitJson(result.payload);
+    }
+    return result.code;
+  } catch (error) {
+    emitError(command, error, Boolean(options.json));
+    return EXIT_FAILURE;
+  }
+}
+
+export function main(argv = process.argv.slice(2)) {
+  const code = run(argv);
+  process.exitCode = code;
+  return code;
+}
+
+const isDirect = process.argv[1] && existsSync(process.argv[1])
+  && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+if (isDirect) {
+  main();
+}
+
+export default { run, main, parseOptions, COMMANDS };