accrete-kit 0.0.0-stage → 0.1.1

package/lib/cli.mjs

@@ -0,0 +1,188 @@
+// Arguments and what the person or agent reads.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { AccreteError } from './fsutil.mjs';
+import { BINARY } from './kernel.mjs';
+import { MARKER, loadScaffold } from './scaffold.mjs';
+import { createWorkspace, findWorkspace, installWorkspace, upgradeWorkspace } from './workspace.mjs';
+
+const USAGE = `Create or upgrade an ACCRETE Workspace, and install its Kernel.
+
+  npx accrete-kit@latest create DIRECTORY [OPTIONS]
+  npx accrete-kit@latest create .                    Add to this directory or repository
+  npx accrete-kit@latest upgrade [OPTIONS]
+  npx accrete-kit@<version> install [OPTIONS]        Restore this host's Kernel after a clone
+
+Create options:
+  --name NAME  --id ID  --timezone IANA_ZONE
+  --agents codex,claude|codex|claude|none
+  --no-git  --no-install  --json
+
+Upgrade options:
+  --project PATH     Otherwise the nearest ancestor ${MARKER}
+  --dry-run          Report the decisions and write nothing
+  --agents codex,claude|codex|claude|none
+  --accept PATH      Record a resolved candidate, relative to the Workspace
+  --no-install  --json
+
+Install options:
+  --project PATH  --json
+
+--no-install skips installing the Kernel binary. Owner edits are preserved: a conflict
+leaves the file alone and writes a candidate under .accrete/template-upgrades/. The Kernel
+runs as ${BINARY}; accrete-kit does not forward commands to it.`;
+
+const OPTIONS = {
+  name: { type: 'string' },
+  id: { type: 'string' },
+  timezone: { type: 'string' },
+  agents: { type: 'string' },
+  'no-git': { type: 'boolean' },
+  'no-install': { type: 'boolean' },
+  project: { type: 'string' },
+  'dry-run': { type: 'boolean' },
+  accept: { type: 'string' },
+  json: { type: 'boolean' },
+  help: { type: 'boolean', short: 'h' },
+  version: { type: 'boolean', short: 'v' }
+};
+
+function refuse(values, names, context) {
+  for (const name of names) {
+    if (values[name] !== undefined) throw new AccreteError('invalid', `--${name} does not apply ${context}`);
+  }
+}
+
+function nextSteps(receipt, cwd) {
+  const steps = [];
+  const fresh = receipt.action === 'create' && !receipt.skipped;
+  if (fresh) {
+    const relative = path.relative(cwd, receipt.project_root);
+    if (relative) steps.push(`cd ${relative.startsWith('..') ? receipt.project_root : relative}`);
+  }
+  if (receipt.kernel?.action === 'skipped' && !receipt.dry_run) steps.push(`npx accrete-kit@${receipt.template_version} install`);
+  if (fresh) {
+    if (receipt.ok) steps.push(`${BINARY} --version`);
+    steps.push('Start your agent at the Workspace root; AGENTS.md is its entry point');
+  }
+  return steps;
+}
+
+function printHuman(receipt) {
+  const out = line => process.stdout.write(`${line}\n`);
+  const where = receipt.project_root;
+  if (receipt.skipped) out(receipt.message);
+  else if (receipt.action === 'accept') out(`${receipt.dry_run ? 'Would accept' : 'Accepted'} ${receipt.accepted.destination} in ${where}`);
+  else if (receipt.action === 'install') out(`Kernel for ${receipt.kernel.platform} in ${where}`);
+  else if (receipt.dry_run) out(`Would apply template ${receipt.template_version} to ${where}`);
+  else {
+    const verb = receipt.action === 'upgrade' ? 'Upgraded' : receipt.created ? 'Created' : 'Updated';
+    out(`${verb} ACCRETE Workspace ${where} (template ${receipt.template_version})`);
+  }
+  if (receipt.git_initialized) out('Initialized a Git repository; nothing is committed.');
+  if (receipt.kernel) out(`Kernel: accrete ${receipt.kernel.version} at ${receipt.kernel.path} (${receipt.kernel.action})`);
+  if (receipt.files) {
+    const counts = new Map();
+    for (const { action } of receipt.files) counts.set(action, (counts.get(action) ?? 0) + 1);
+    if (counts.size > 0) out(`  ${[...counts].map(([action, count]) => `${action}: ${count}`).join(', ')}`);
+    for (const { destination, candidate, next } of receipt.files) {
+      if (candidate) out(`  pending ${destination}\n    candidate ${candidate}\n    ${next}`);
+    }
+  }
+  for (const destination of receipt.detached ?? []) out(`  detached ${destination} (edited; no longer managed)`);
+  for (const destination of receipt.locally_deleted ?? []) out(`  kept deleted ${destination}`);
+  for (const { destination, error, retry } of receipt.failed) {
+    out(`  failed ${destination}: ${error}`);
+    if (retry) out(`    retry: ${retry}`);
+  }
+  if (receipt.next_steps.length > 0) {
+    out('\nNext steps:');
+    for (const step of receipt.next_steps) out(`  ${step}`);
+  }
+}
+
+function selectWorkspace(values, directories, cwd, command) {
+  if (directories.length > 0) throw new AccreteError('invalid', `${command} takes no directory; use --project ${directories[0]}`);
+  const named = values.project === undefined ? null : path.resolve(cwd, values.project);
+  const root = named === null ? findWorkspace(cwd) : fs.existsSync(named) ? fs.realpathSync(named) : null;
+  if (!root || !fs.existsSync(path.join(root, MARKER))) {
+    throw new AccreteError('not_found', `No ACCRETE Workspace (${MARKER}) at ${values.project ?? `or above ${cwd}`}; create one with npx accrete-kit@latest create`);
+  }
+  return root;
+}
+
+function install(values, directories, scaffold, cwd) {
+  refuse(values, ['name', 'id', 'timezone', 'no-git', 'no-install', 'dry-run', 'agents', 'accept'], 'to install');
+  return installWorkspace(selectWorkspace(values, directories, cwd, 'install'), scaffold);
+}
+
+function upgrade(values, directories, scaffold, cwd) {
+  refuse(values, ['name', 'id', 'timezone', 'no-git'], 'to upgrade');
+  if (values.accept !== undefined && values.agents !== undefined) throw new AccreteError('invalid', '--accept and --agents are separate operations');
+  const root = selectWorkspace(values, directories, cwd, 'upgrade');
+  return upgradeWorkspace(root, {
+    agents: values.agents,
+    accept: values.accept,
+    dryRun: values['dry-run'],
+    install: !values['no-install']
+  }, scaffold);
+}
+
+function create(values, directories, scaffold, cwd) {
+  refuse(values, ['project', 'dry-run', 'accept'], 'to create');
+  if (directories.length !== 1) throw new AccreteError('invalid', 'create takes one directory, or . for this one');
+  return createWorkspace(path.resolve(cwd, directories[0]), {
+    name: values.name,
+    id: values.id,
+    timezone: values.timezone,
+    agents: values.agents,
+    git: !values['no-git'],
+    install: !values['no-install']
+  }, scaffold);
+}
+
+const COMMANDS = { create, upgrade, install };
+
+export function main(argv, cwd = process.cwd()) {
+  const jsonRequested = argv.includes('--json');
+  try {
+    let parsed;
+    try {
+      parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true });
+    } catch (error) {
+      throw new AccreteError('invalid', error.message);
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+      process.stdout.write(`${USAGE}\n`);
+      return 0;
+    }
+    const scaffold = loadScaffold();
+    if (values.version) {
+      process.stdout.write(`accrete-kit ${scaffold.template_version} (carries Kernel ${scaffold.kernel_version})\n`);
+      return 0;
+    }
+    const [command, ...directories] = positionals;
+    if (!Object.hasOwn(COMMANDS, command ?? '')) {
+      throw new AccreteError('invalid', command === undefined ? 'Name a subcommand: create, upgrade or install' : `Unknown subcommand ${command}; use create, upgrade or install`);
+    }
+    const receipt = COMMANDS[command](values, directories, scaffold, cwd);
+    receipt.next_steps = nextSteps(receipt, cwd);
+    if (receipt.warning) process.stderr.write(`warning: ${receipt.warning}\n`);
+    for (const warning of receipt.warnings ?? []) process.stderr.write(`warning: ${warning}\n`);
+    if (receipt.cleanup_warning) process.stderr.write(`warning: cleanup: ${receipt.cleanup_warning}\n`);
+    if (values.json) process.stdout.write(`${JSON.stringify(receipt)}\n`);
+    else printHuman(receipt);
+    return receipt.ok ? 0 : 7;
+  } catch (caught) {
+    const error = caught instanceof AccreteError ? caught : new AccreteError('storage', caught.message);
+    if (jsonRequested) process.stderr.write(`${JSON.stringify(error)}\n`);
+    else {
+      process.stderr.write(`${error.kind}: ${error.message}\n`);
+      if (error.message.includes('subcommand')) process.stderr.write(`\n${USAGE}\n`);
+      if (error.details) process.stderr.write(`${JSON.stringify(error.details, null, 2)}\n`);
+    }
+    return error.exitCode;
+  }
+}

package/lib/fsutil.mjs

@@ -0,0 +1,135 @@
+// Errors and the file operations every other module goes through.
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+// The same kinds and exit codes as the accrete Kernel.
+const EXIT_CODES = {
+  invalid: 2, unsupported_format: 2, config: 3, not_found: 3, conflict: 4,
+  dependency: 5, storage: 6, external: 7, incomplete: 7
+};
+
+export class AccreteError extends Error {
+  constructor(kind, message, details = null) {
+    super(message);
+    this.kind = kind;
+    this.details = details;
+    this.exitCode = EXIT_CODES[kind] ?? 6;
+  }
+  toJSON() {
+    return {
+      ok: false,
+      error: { kind: this.kind, message: this.message, details: this.details },
+      exit_code: this.exitCode
+    };
+  }
+}
+
+export const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+
+/** A forward-slash relative path with normal components only. */
+export function checkRelative(text) {
+  const portable = typeof text === 'string' && text.length > 0
+    && !/[\\:\u0000-\u001f]/.test(text)
+    && !text.startsWith('/')
+    && !text.split('/').some(part => part === '' || part === '.' || part === '..');
+  if (!portable) throw new AccreteError('invalid', `Paths must be portable relative paths without traversal: ${text}`);
+  return text;
+}
+
+const lstat = target => {
+  try {
+    return fs.lstatSync(target);
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+    throw error;
+  }
+};
+
+export function refuseSymlinks(root, relative) {
+  let current = root;
+  for (const part of relative.split('/')) {
+    current = path.join(current, part);
+    if (lstat(current)?.isSymbolicLink()) {
+      throw new AccreteError('conflict', `Path traverses a symbolic link: ${current}`);
+    }
+  }
+}
+
+/**
+ * What is at a destination, without following links: `missing`, a regular
+ * `file` with its bytes, or `other` for a directory, symbolic link or special
+ * file at or above it.
+ */
+export function readCurrent(root, destination) {
+  const parts = checkRelative(destination).split('/');
+  let current = root;
+  for (const [index, part] of parts.entries()) {
+    current = path.join(current, part);
+    const stat = lstat(current);
+    if (!stat) return { kind: 'missing' };
+    if (index === parts.length - 1) {
+      return stat.isFile() ? { kind: 'file', bytes: fs.readFileSync(current) } : { kind: 'other' };
+    }
+    if (!stat.isDirectory()) return { kind: 'other' };
+  }
+  return { kind: 'other' };
+}
+
+function syncDirectory(directory) {
+  let fd;
+  try {
+    fd = fs.openSync(directory, 'r');
+    fs.fsyncSync(fd);
+  } catch (error) {
+    // Some platforms cannot open or synchronize a directory.
+    if (!['EISDIR', 'EPERM', 'EINVAL', 'ENOTSUP'].includes(error.code)) throw error;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+/**
+ * Temp sibling, fsync, rename, fsync the directory. The temp name is fixed, so
+ * the next write of this path replaces one a killed run left behind.
+ */
+export function atomicWrite(target, bytes, { mode: requested } = {}) {
+  const directory = path.dirname(target);
+  const firstCreated = fs.mkdirSync(directory, { recursive: true });
+  const temporary = path.join(directory, `.${path.basename(target)}.accrete-tmp`);
+  const mode = requested ?? lstat(target)?.mode;
+  fs.rmSync(temporary, { force: true });
+  try {
+    const fd = fs.openSync(temporary, 'wx', 0o644);
+    try {
+      fs.writeFileSync(fd, bytes);
+      if (mode !== undefined) fs.fchmodSync(fd, mode & 0o7777);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(temporary, target);
+  } catch (error) {
+    fs.rmSync(temporary, { force: true });
+    throw error;
+  }
+  syncDirectory(directory);
+  if (firstCreated) {
+    for (let up = directory; up !== path.dirname(firstCreated); up = path.dirname(up)) syncDirectory(path.dirname(up));
+  }
+}
+
+export function removeWithEmptyParents(root, destination) {
+  const target = path.join(root, destination);
+  fs.rmSync(target);
+  let directory = path.dirname(target);
+  while (directory !== root) {
+    try {
+      fs.rmdirSync(directory);
+    } catch {
+      break;
+    }
+    directory = path.dirname(directory);
+  }
+  syncDirectory(directory);
+}