kido-workspace 0.1.0

package/lib/workspace.cjs

@@ -0,0 +1,342 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const packageRoot = path.resolve(__dirname, '..');
+const pkg = require('../package.json');
+const resourceKinds = ['skills', 'rules', 'templates'];
+const manifestPath = '.agents/kido-install.json';
+// During legacy preflight only, inspect the old physical tree without following .agents.
+let legacyWorkspace = null;
+
+const help = `Usage: kido-workspace <init|upgrade> [--dry-run]
+       kido-workspace upgrade [--keep-local <resource-path>] [--dry-run]
+
+  init       Install bundled resources in the current directory.
+  upgrade    Update installed resources, preserving local customizations.
+  --dry-run  Show changes without writing files.
+  --keep-local <path>  Accept a reviewed local resource without overwriting it.
+  --version  Show the running package version.
+
+To use the latest release: npx ${pkg.name}@latest upgrade
+`;
+
+const agentBootstrap = `# Workspace agent instructions
+
+Read [KIDO workflow](.agents/skills/kido-workflow/SKILL.md) for task routing and permission boundaries.
+For onboarding, read [KIDO onboarding](.agents/skills/kido-onboarding/SKILL.md).
+
+This directory is the shared workspace root. Application components belong under packages/ after the user chooses move or symlink placement during onboarding.
+Project context belongs under context/, including TypeSpec API contracts under context/contracts/.
+Preserve existing policies and source repositories. Do not read environment files or run project scripts, commit, push, or deploy without matching authorization.
+`;
+const claudeBootstrap = `# Workspace instructions
+
+Read [AGENTS.md](AGENTS.md) when present and follow applicable project instructions.
+Shared skills, rules and templates live under .agents/.
+For task routing, read [KIDO workflow](.agents/skills/kido-workflow/SKILL.md).
+For onboarding, read [KIDO onboarding](.agents/skills/kido-onboarding/SKILL.md).
+`;
+
+function stat(file) {
+  try { return fs.lstatSync(file); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+function digest(contents) {
+  return crypto.createHash('sha256').update(contents).digest('hex');
+}
+
+// Inspect every ancestor with lstat; never follow a workspace symlink for a write.
+function safePath(root, relative) {
+  if (root === legacyWorkspace) relative = relative.replace(/^\.agents(?=\/|$)/, 'agents');
+  const parts = relative.split('/');
+  if (parts.some((part) => !part || part === '.' || part === '..' || part.includes('\\') || part.includes(':'))) {
+    throw new Error(`Invalid resource path: ${relative}`);
+  }
+  let current = root;
+  for (let index = 0; index < parts.length; index++) {
+    current = path.join(current, parts[index]);
+    const info = stat(current);
+    if (info?.isSymbolicLink()) throw new Error(`Refusing a symlink destination: ${relative}`);
+    if (info && index < parts.length - 1 && !info.isDirectory()) {
+      throw new Error(`Destination parent is not a directory: ${relative}`);
+    }
+  }
+  return current;
+}
+
+function isResource(relative) {
+  return resourceKinds.some((kind) => relative.startsWith(`.agents/${kind}/`)) &&
+    !relative.split('/').some((part) => /^\.env(?:\.|$)/i.test(part));
+}
+
+function readBundle() {
+  const resources = new Map();
+  function walk(source, destination) {
+    for (const entry of fs.readdirSync(source, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const relative = `${destination}/${entry.name}`;
+      const file = path.join(source, entry.name);
+      if (!isResource(relative)) throw new Error(`Unsupported bundled resource: ${relative}`);
+      if (entry.isSymbolicLink()) throw new Error(`Bundled resources must not contain symlinks: ${relative}`);
+      if (entry.isDirectory()) walk(file, relative);
+      else if (entry.isFile()) {
+        const contents = fs.readFileSync(file);
+        resources.set(relative, { contents, hash: digest(contents) });
+      } else throw new Error(`Unsupported bundled resource: ${relative}`);
+    }
+  }
+  for (const kind of resourceKinds) {
+    const source = path.join(packageRoot, '.agents', kind);
+    if (!stat(source)?.isDirectory() || stat(source).isSymbolicLink()) {
+      throw new Error(`Missing bundled resources: .agents/${kind}`);
+    }
+    walk(source, `.agents/${kind}`);
+  }
+  return resources;
+}
+
+function directory(root, relative, operations) {
+  const file = safePath(root, relative);
+  const info = stat(file);
+  if (info && !info.isDirectory()) throw new Error(`Expected a directory: ${relative}`);
+  if (!info && !operations.some((operation) => operation.type === 'mkdir' && operation.relative === relative)) {
+    operations.push({ type: 'mkdir', relative });
+  }
+}
+
+function link(root, relative, destination, operations) {
+  // Validate the parent separately: the final adapter itself is intentionally a symlink.
+  const parent = path.posix.dirname(relative);
+  if (parent !== '.') directory(root, parent, operations);
+  const file = path.join(root, relative);
+  const info = stat(file);
+  const target = path.relative(path.dirname(file), path.join(root, destination));
+  if (info) {
+    if (!info.isSymbolicLink() || path.resolve(path.dirname(file), fs.readlinkSync(file)) !== path.join(root, destination)) {
+      const oldDestination = destination.replace(/^\.agents\//, 'agents/');
+      if (root === legacyWorkspace && info.isSymbolicLink() &&
+          path.resolve(path.dirname(file), fs.readlinkSync(file)) === path.join(root, oldDestination)) {
+        operations.push({ type: 'relink', relative, target });
+      } else throw new Error(`Adapter already exists with different content: ${relative}`);
+    }
+  } else operations.push({ type: 'link', relative, target });
+}
+
+function adapters(root, resources, operations) {
+  directory(root, '.claude/skills', operations);
+  const skills = new Set([...resources.keys()]
+    .filter((relative) => relative.startsWith('.agents/skills/'))
+    .map((relative) => relative.split('/')[2]));
+  for (const skill of [...skills].sort()) {
+    link(root, `.claude/skills/${skill}`, `.agents/skills/${skill}`, operations);
+  }
+  link(root, '.claude/templates', '.agents/templates', operations);
+}
+
+function readManifest(root) {
+  const file = safePath(root, manifestPath);
+  const info = stat(file);
+  if (!info?.isFile()) throw new Error('No supported KIDO installation found. Run init in the workspace root first.');
+  const manifest = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (manifest.schemaVersion !== 1 || manifest.packageName !== pkg.name ||
+      typeof manifest.templateVersion !== 'string' || typeof manifest.createdAt !== 'string' ||
+      !manifest.files || typeof manifest.files !== 'object' || Array.isArray(manifest.files)) {
+    throw new Error('Unsupported installation metadata. Legacy installs need a reviewed migration; no files were changed.');
+  }
+  for (const [relative, hash] of Object.entries(manifest.files)) {
+    const normalized = root === legacyWorkspace ? relative.replace(/^agents\//, '.agents/') : relative;
+    if (!isResource(normalized) || typeof hash !== 'string' || !/^[a-f0-9]{64}$/.test(hash)) {
+      throw new Error(`Invalid installation metadata entry: ${relative}`);
+    }
+    safePath(root, normalized);
+  }
+  if (root === legacyWorkspace) {
+    if (Object.keys(manifest.files).some((relative) => !relative.startsWith('agents/'))) {
+      throw new Error('Legacy metadata contains mixed resource roots; review migration manually.');
+    }
+    manifest.files = Object.fromEntries(Object.entries(manifest.files).map(([relative, hash]) => [relative.replace(/^agents\//, '.agents/'), hash]));
+    manifest.conflicts = (manifest.conflicts || []).map((relative) => relative.replace(/^agents\//, '.agents/'));
+  }
+  return manifest;
+}
+
+function init(root, resources) {
+  if (stat(path.join(root, '.agents'))) {
+    throw new Error('.agents already exists. Use upgrade for a managed installation; otherwise review the existing layout first.');
+  }
+  const operations = [];
+  directory(root, '.agents', operations);
+  if (stat(safePath(root, manifestPath))) throw new Error('KIDO is already initialized. Use upgrade.');
+  for (const kind of resourceKinds) {
+    const relative = `.agents/${kind}`;
+    if (stat(safePath(root, relative))) throw new Error(`Resource directory already exists: ${relative}`);
+    directory(root, relative, operations);
+  }
+  for (const relative of ['context/contracts', 'epics', 'packages']) directory(root, relative, operations);
+  for (const [relative, resource] of resources) {
+    safePath(root, relative);
+    operations.push({ type: 'write', relative, contents: resource.contents });
+  }
+  for (const [relative, contents] of [['AGENTS.md', agentBootstrap], ['CLAUDE.md', claudeBootstrap]]) {
+    // Existing entrypoints, including symlinks, belong to the project and are left alone.
+    if (!stat(path.join(root, relative))) operations.push({ type: 'write', relative, contents });
+  }
+  adapters(root, resources, operations);
+  const timestamp = new Date().toISOString();
+  const manifest = {
+    schemaVersion: 1, packageName: pkg.name, templateVersion: pkg.version,
+    createdAt: timestamp, updatedAt: timestamp,
+    files: Object.fromEntries([...resources].map(([relative, resource]) => [relative, resource.hash])),
+    conflicts: [],
+  };
+  operations.push({ type: 'manifest', relative: manifestPath, contents: JSON.stringify(manifest, null, 2) + '\n' });
+  return { operations, conflicts: [] };
+}
+
+function upgrade(root, resources, keepLocal) {
+  const previous = readManifest(root);
+  const operations = [];
+  if (root === legacyWorkspace) {
+    operations.push({ type: 'migrate', relative: '.agents' });
+    for (const relative of ['AGENTS.md', 'CLAUDE.md']) {
+      const file = path.join(root, relative);
+      if (!stat(file)?.isFile()) continue;
+      const original = fs.readFileSync(file, 'utf8');
+      const contents = original.replace(/(?<![\w./-])agents\/(skills|rules|templates|kido-install\.json)/g, '.agents/$1');
+      if (contents !== original) operations.push({ type: 'write', relative, contents });
+    }
+  }
+  const conflicts = [];
+  const files = { ...previous.files };
+  const paths = [...new Set([...Object.keys(files), ...resources.keys()])].sort();
+  for (const relative of keepLocal) {
+    if (!isResource(relative) || !paths.includes(relative)) {
+      throw new Error(`--keep-local requires a managed resource path: ${relative}`);
+    }
+    safePath(root, relative);
+  }
+  for (const relative of paths) {
+    const file = safePath(root, relative);
+    const info = stat(file);
+    if (info && !info.isFile()) throw new Error(`Expected a resource file: ${relative}`);
+    const current = info ? digest(fs.readFileSync(file)) : undefined;
+    const baseline = previous.files[relative];
+    const incoming = resources.get(relative);
+    if (keepLocal.has(relative)) {
+      if (incoming) files[relative] = incoming.hash;
+      else delete files[relative];
+      continue;
+    }
+    if (incoming) {
+      if (current === incoming.hash) files[relative] = incoming.hash;
+      else if (baseline === incoming.hash) {
+        // Only local contents changed (including an intentional local deletion).
+        // Retain the original baseline so a future upstream change detects the conflict.
+      } else if (current === baseline) {
+        operations.push({ type: 'write', relative, contents: incoming.contents });
+        files[relative] = incoming.hash;
+      } else conflicts.push(relative);
+    } else if (current === baseline || current === undefined) {
+      if (current !== undefined) operations.push({ type: 'remove', relative });
+      delete files[relative];
+    } else conflicts.push(relative);
+  }
+  adapters(root, resources, operations);
+  const manifest = { ...previous, templateVersion: pkg.version, files, conflicts };
+  // No-op upgrades should leave the installation byte-for-byte unchanged.
+  if (JSON.stringify(manifest) !== JSON.stringify(previous) || operations.length > 0) {
+    manifest.updatedAt = new Date().toISOString();
+    operations.push({ type: 'manifest', relative: manifestPath, contents: JSON.stringify(manifest, null, 2) + '\n' });
+  }
+  return { operations, conflicts };
+}
+
+function apply(root, operation) {
+  const file = path.join(root, operation.relative);
+  if (operation.type === 'migrate') {
+    const previous = path.join(root, 'agents');
+    if (!stat(file)?.isSymbolicLink() || path.resolve(root, fs.readlinkSync(file)) !== previous ||
+        !stat(previous)?.isDirectory() || stat(previous).isSymbolicLink()) {
+      throw new Error('Legacy layout changed during migration; stopped.');
+    }
+    const target = fs.readlinkSync(file);
+    fs.unlinkSync(file);
+    try { fs.renameSync(previous, file); }
+    catch (error) {
+      fs.symlinkSync(target, file, process.platform === 'win32' ? 'junction' : 'dir');
+      throw error;
+    }
+    return;
+  }
+  if (operation.type === 'link' || operation.type === 'relink') {
+    if (operation.type === 'relink') fs.unlinkSync(file);
+    fs.symlinkSync(operation.target, file, process.platform === 'win32' ? 'junction' : 'dir');
+    return;
+  }
+  safePath(root, operation.relative);
+  if (operation.type === 'mkdir') fs.mkdirSync(file, { recursive: true });
+  else if (operation.type === 'remove') fs.unlinkSync(file);
+  else {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    if (operation.type === 'manifest') {
+      const temporary = `${file}.${crypto.randomUUID()}.tmp`;
+      try {
+        fs.writeFileSync(temporary, operation.contents, { flag: 'wx' });
+        fs.renameSync(temporary, file);
+      } finally {
+        if (stat(temporary)) fs.unlinkSync(temporary);
+      }
+    } else fs.writeFileSync(file, operation.contents);
+  }
+}
+
+function run(args) {
+  if (args.length === 0 || (args.length === 1 && ['--help', '-h'].includes(args[0]))) {
+    console.log(help);
+    return 0;
+  }
+  if (args.length === 1 && ['--version', '-v'].includes(args[0])) {
+    console.log(pkg.version);
+    return 0;
+  }
+  const [command, ...flags] = args;
+  if (!['init', 'upgrade'].includes(command)) throw new Error(`Unknown command: ${command}.\n${help}`);
+  if (flags.length === 1 && ['--help', '-h'].includes(flags[0])) { console.log(help); return 0; }
+  let dryRun = false;
+  const keepLocal = new Set();
+  for (let index = 0; index < flags.length; index++) {
+    const flag = flags[index];
+    if (flag === '--dry-run' && !dryRun) dryRun = true;
+    else if (flag === '--keep-local' && command === 'upgrade' && flags[index + 1] && !flags[index + 1].startsWith('-')) {
+      keepLocal.add(flags[++index]);
+    } else throw new Error(`Unsupported or incomplete argument: ${flag}.\n${help}`);
+  }
+  const root = fs.realpathSync(process.cwd());
+  const resources = readBundle();
+  let result;
+  try {
+    const adapter = path.join(root, '.agents');
+    if (command === 'upgrade' && stat(adapter)?.isSymbolicLink() &&
+        path.resolve(root, fs.readlinkSync(adapter)) === path.join(root, 'agents')) {
+      legacyWorkspace = root;
+    }
+    result = command === 'init' ? init(root, resources) : upgrade(root, resources, keepLocal);
+  } finally { legacyWorkspace = null; }
+  console.log(`${dryRun ? 'Dry run: ' : ''}${command} ${pkg.name}@${pkg.version} in ${root}`);
+  for (const operation of result.operations) {
+    console.log(`  ${operation.type} ${operation.relative}`);
+    if (!dryRun) apply(root, operation);
+  }
+  for (const conflict of result.conflicts) console.error(`  conflict (kept local): ${conflict}`);
+  if (result.conflicts.length) {
+    console.error('Compare conflicts with the bundled resources. After reviewing a local merge, use upgrade --keep-local <path>. Exit code: 2.');
+    return 2;
+  }
+  if (command === 'init') console.log('Next: ask your agent to onboard this workspace.');
+  else console.log(result.operations.length ? 'Upgrade complete.' : 'Already up to date.');
+  return 0;
+}
+
+module.exports = { run };

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "kido-workspace",
+  "version": "0.1.0",
+  "description": "Initialize and upgrade KIDO skills, rules and templates in a workspace",
+  "license": "MIT",
+  "bin": {
+    "kido-workspace": "bin/kido-workspace.cjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    ".agents/skills/",
+    ".agents/rules/",
+    ".agents/templates/"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.cjs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}