@agilno-tech/rivet 0.1.0-alpha.0

package/src/commands/protocols.js

@@ -0,0 +1,228 @@
+import * as filesystem from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import YAML from 'yaml';
+
+import { loadProjectConfig } from '../config/load.js';
+import { CliError, EXIT_CODES } from '../cli/output.js';
+
+import { MAX_PROTOCOL_BYTES, PROTOCOL_DIRECTORY, MUTATION_LOCK, DIGEST, safeText, safeId, sameIdentity, lstatIfExists, readBounded, protocolRoot, canonicalBody, bodyDigest, validateDocument, protocolPath, discover, publicProtocol } from '../protocols/project.js';
+import { protocolCompleteness, requireProtocolCompleteness } from '../protocols/project.js';
+const MAX_QUERY_LENGTH = 256;
+const SUBCOMMANDS = new Set(['add', 'import', 'validate', 'find', 'show', 'update', 'retire']);
+function fail(message, code = 'INVALID_INPUT') { throw new CliError(message, code); }
+
+function draftGuidance(id, revision) {
+  return `Write the missing sections in a project-contained Markdown source file without inventing team policy, then run rivet protocols update ${id} --from=<file> --expected-revision=${revision}. Add --publish only after review and complete validation.`;
+}
+
+function now() {
+  return new Date().toISOString();
+}
+
+function render(metadata, body) {
+  const frontmatter = YAML.stringify(metadata, { lineWidth: 0 }).trimEnd();
+  return `---\n${frontmatter}\n---\n\n${canonicalBody(body)}`;
+}
+
+function atomicWrite(path, source, fs, expectedParent, expectedDigest = null) {
+  const parent = resolve(path, '..');
+  const temporary = join(parent, `.rivet-protocol-${randomUUID()}.tmp`);
+  const lockPath = join(parent, MUTATION_LOCK);
+  let descriptor;
+  let lock;
+  try {
+    lock = fs.openSync(lockPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+    const currentParent = lstatIfExists(parent, fs);
+    if (!currentParent || currentParent.isSymbolicLink() || !currentParent.isDirectory() || !sameIdentity(expectedParent, currentParent)) {
+      fail('Protocol directory changed during validation.', 'REPOSITORY_CONFLICT');
+    }
+    const current = lstatIfExists(path, fs);
+    if (expectedDigest === null) {
+      if (current) fail('Protocol already exists.', 'REPOSITORY_CONFLICT');
+    } else {
+      const id = path.slice(parent.length + 1, -3);
+      const observed = validateDocument(readBounded(path, fs, `Protocol '${id}'`), id);
+      if (observed.metadata.digest !== expectedDigest) fail('Protocol revision conflict.', 'REPOSITORY_CONFLICT');
+    }
+    descriptor = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+    fs.writeFileSync(descriptor, source, { encoding: 'utf8' });
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    const finalParent = lstatIfExists(parent, fs);
+    if (!finalParent || finalParent.isSymbolicLink() || !finalParent.isDirectory() || !sameIdentity(expectedParent, finalParent)) {
+      fail('Protocol directory changed during validation.', 'REPOSITORY_CONFLICT');
+    }
+    fs.renameSync(temporary, path);
+  } catch (error) {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+    try { fs.unlinkSync(temporary); } catch {}
+    if (error instanceof CliError) throw error;
+    fail('Protocol write could not be completed safely.', 'REPOSITORY_CONFLICT');
+  } finally {
+    if (lock !== undefined) {
+      try { fs.closeSync(lock); } catch {}
+      try { fs.unlinkSync(lockPath); } catch {}
+    }
+  }
+}
+
+function sourcePath(root, input, fs) {
+  if (typeof input !== 'string' || input.length < 1 || input.length > 512 || input.includes('\0')) fail("Option '--from' is invalid.");
+  const normalized = input.replaceAll('\\', '/');
+  const absolute = resolve(root.root, normalized);
+  const within = relative(root.root, absolute);
+  if (isAbsolute(normalized) || !within || within === '..' || within.startsWith(`..${sep}`)) fail("Option '--from' must stay within the project.");
+  let current = root.root;
+  for (const part of within.split(sep).slice(0, -1)) {
+    current = join(current, part);
+    const status = lstatIfExists(current, fs);
+    if (!status || status.isSymbolicLink() || !status.isDirectory()) fail('Protocol import source has an unsafe ancestor.', 'REPOSITORY_CONFLICT');
+  }
+  return absolute;
+}
+
+function requireFlags(parsed) {
+  if (!parsed || parsed.command !== 'protocols' || !SUBCOMMANDS.has(parsed.subcommand)
+    || !Array.isArray(parsed.operands) || !parsed.flags || typeof parsed.flags !== 'object') fail('Invalid protocols command.');
+  const allowed = new Set(['project', 'json', 'from', 'include-drafts', 'include-retired', 'publish', 'expected-revision', 'expected-digest']);
+  if (Object.keys(parsed.flags).some(key => !allowed.has(key))) fail('Invalid protocols command options.');
+  if (parsed.flags.project !== undefined && (typeof parsed.flags.project !== 'string' || parsed.flags.project.length === 0)) fail("Option '--project' is invalid.");
+  return parsed;
+}
+
+function emit(dependencies, parsed, result, code = EXIT_CODES.SUCCESS) {
+  const json = parsed?.flags?.json === true;
+  if (json && code !== EXIT_CODES.SUCCESS) {
+    dependencies.output.json({ ok: false, error: result.error ?? { code: 'INTERNAL_ERROR', exitCode: code, message: 'Protocol operation failed.' } }, 'stderr');
+  } else if (json) {
+    dependencies.output.json({ ok: true, command: 'protocols', result }, 'stdout');
+  }
+  else if (code === EXIT_CODES.SUCCESS) dependencies.output.log(JSON.stringify(result, null, 2));
+  else dependencies.output.error(`ERROR: ${result.error?.message ?? result.message ?? 'Protocol operation failed.'}`);
+  return code;
+}
+
+function errorResult(error) {
+  return {
+    error: {
+      code: error.code ?? 'INTERNAL_ERROR',
+      exitCode: error.exitCode ?? EXIT_CODES.INTERNAL_ERROR,
+      message: error.safeMessage ?? error.message ?? 'Protocol operation failed.',
+    },
+  };
+}
+
+export async function protocolsCommand(input, dependencies = {}) {
+  let parsed;
+  try {
+    parsed = requireFlags(input);
+    const fs = dependencies.fs ?? filesystem;
+    const projectRoot = resolve(parsed.flags.project ?? dependencies.cwd?.() ?? process.cwd());
+    await (dependencies.configLoader ?? loadProjectConfig)(projectRoot, { fs });
+    const root = protocolRoot(projectRoot, fs, { create: ['add', 'import'].includes(parsed.subcommand) });
+    const operands = parsed.operands;
+    const command = parsed.subcommand, flags = parsed.flags;
+    if (flags.from !== undefined && !['add','import','update'].includes(command)) fail("Option '--from' is only valid for add/import/update.");
+    if (flags.publish !== undefined && command !== 'update') fail("Only update --publish activates a protocol.");
+    if ((flags['include-drafts'] !== undefined || flags['include-retired'] !== undefined) && !['find','show'].includes(command)) fail('Status inclusion options are only valid for find/show.');
+    if (flags['expected-digest'] !== undefined && command !== 'show') fail("Option '--expected-digest' is only valid for show.");
+    if (flags['expected-revision'] !== undefined && !['update','retire','show'].includes(command)) fail("Option '--expected-revision' is only valid for update/retire/show.");
+    if (command === 'show' && (flags['expected-revision'] !== undefined || flags['expected-digest'] !== undefined)
+      && (!/^[1-9][0-9]{0,9}$/.test(String(flags['expected-revision'] ?? '')) || Number(flags['expected-revision']) > 1_000_000_000 || !DIGEST.test(flags['expected-digest'] ?? ''))) fail('Exact protocol lookup requires both --expected-revision and --expected-digest from the approved run.');
+    if (command === 'retire' && (operands.length !== 1 || !/^[1-9][0-9]{0,9}$/.test(String(flags['expected-revision'] ?? '')) || Number(flags['expected-revision']) > 1_000_000_000)) fail('Use rivet protocols retire <slug> --expected-revision=<current revision>.');
+    if (parsed.subcommand === 'add' && (operands.length !== 1 || (parsed.flags.from !== undefined && typeof parsed.flags.from !== 'string'))) fail('Use rivet protocols add <slug>.');
+    if (parsed.subcommand === 'import' && (operands.length !== 1 || typeof parsed.flags.from !== 'string')) fail('Use rivet protocols import <slug> --from=<path>.');
+    if (parsed.subcommand === 'validate' && operands.length > 1) fail('Use rivet protocols validate [<slug>].');
+    if (parsed.subcommand === 'find' && (operands.length !== 1 || typeof operands[0] !== 'string' || operands[0].length < 1 || operands[0].length > MAX_QUERY_LENGTH)) fail('Use rivet protocols find <query>.');
+    if (parsed.subcommand === 'show' && operands.length !== 1) fail('Use rivet protocols show <slug>.');
+    if (parsed.subcommand === 'update' && (operands.length !== 1 || typeof parsed.flags.from !== 'string' || parsed.flags.publish && parsed.flags['include-drafts'])) fail('Use rivet protocols update <slug> --from=<path> [--publish].');
+    if (parsed.subcommand === 'update' && (!/^\d+$/.test(String(parsed.flags['expected-revision'] ?? '')) || Number(parsed.flags['expected-revision']) < 1)) fail("Option '--expected-revision' is required for update.");
+
+    if (parsed.subcommand === 'add' && parsed.flags.from === undefined) {
+      const id = safeId(operands[0]);
+      const path = protocolPath(root, id);
+      if (lstatIfExists(path, fs)) fail(`Protocol '${id}' already exists.`, 'REPOSITORY_CONFLICT');
+      const metadata = { schemaVersion: 1, id, title: id.replaceAll('-', ' ').replace(/\b\w/g, letter => letter.toUpperCase()), status: 'draft', revision: 1, updatedAt: now() };
+      const body = canonicalBody(`# ${metadata.title}\n\n## Owner\n\n## Purpose\n\n## Applies when\n\n## Procedure\n\n## Required checks and evidence\n`);
+      metadata.digest = bodyDigest(metadata, body);
+      const source = render(metadata, body);
+      const record = validateDocument(source, id);
+      atomicWrite(path, source, fs, root.identity);
+      return emit(dependencies, parsed, { protocol: publicProtocol(record), message: `Created draft protocol '${id}'. ${draftGuidance(id, 1)}` });
+    }
+
+    if (parsed.subcommand === 'import' || parsed.subcommand === 'add') {
+      const id = safeId(operands[0]);
+      const path = protocolPath(root, id);
+      if (lstatIfExists(path, fs)) fail(`Protocol '${id}' already exists.`, 'REPOSITORY_CONFLICT');
+      const body = canonicalBody(readBounded(sourcePath(root, parsed.flags.from, fs), fs, 'Protocol import source'));
+      const heading = body.match(/^#\s+(\S.*)$/m);
+      if (!heading) fail('Protocol import source must contain a Markdown heading.');
+      const metadata = { schemaVersion: 1, id, title: safeText(heading[1].trim(), 120, 'Protocol title'), status: 'draft', revision: 1, updatedAt: now() };
+      metadata.digest = bodyDigest(metadata, body);
+      const source = render(metadata, body);
+      const record = validateDocument(source, id);
+      atomicWrite(path, source, fs, root.identity);
+      return emit(dependencies, parsed, { protocol: publicProtocol(record), message: `Imported draft protocol '${id}'. ${draftGuidance(id, 1)}` });
+    }
+
+    if (parsed.subcommand === 'show') {
+      const id = safeId(operands[0]);
+      const record = validateDocument(readBounded(protocolPath(root, id), fs, `Protocol '${id}'`), id);
+      if (!record || (record.metadata.status === 'draft' && parsed.flags['include-drafts'] !== true) || (record.metadata.status === 'retired' && parsed.flags['include-retired'] !== true)) fail(`Protocol '${id}' was not found.`);
+      if (parsed.flags['expected-revision'] !== undefined && (record.metadata.status !== 'active' || record.metadata.revision !== Number(parsed.flags['expected-revision']) || record.metadata.digest !== parsed.flags['expected-digest'])) fail('Selected protocol changed or is no longer active. Create a new reviewed proposal.', 'REPOSITORY_CONFLICT');
+      return emit(dependencies, parsed, { protocol: publicProtocol(record, true), message: `Showing protocol '${id}'.` });
+    }
+
+    const all = discover(root, fs, true);
+    if (parsed.subcommand === 'validate') {
+      const records = operands.length === 1 ? all.filter(record => record.metadata.id === operands[0]) : all;
+      if (operands.length === 1 && records.length === 0) fail(`Protocol '${operands[0]}' was not found.`);
+      return emit(dependencies, parsed, { protocols: records.map(record => publicProtocol(record)), message: `Validated integrity of ${records.length} protocol${records.length === 1 ? '' : 's'}. Completeness diagnostics are reported separately; incomplete records cannot publish a new revision.` });
+    }
+    if (parsed.subcommand === 'find') {
+      const query = parsed.operands[0].normalize('NFKC').toLocaleLowerCase();
+      const records = discover(root, fs, parsed.flags['include-drafts'] === true, parsed.flags['include-retired'] === true)
+        .filter(record => `${record.metadata.title}\n${record.body}`.toLocaleLowerCase().includes(query));
+      return emit(dependencies, parsed, { protocols: records.map(record => publicProtocol(record)), message: `Found ${records.length} matching protocol${records.length === 1 ? '' : 's'}.` });
+    }
+
+
+    const id = safeId(operands[0]);
+    const current = all.find(record => record.metadata.id === id);
+    if (!current) fail(`Protocol '${id}' was not found.`);
+    if (current.metadata.revision !== Number(parsed.flags['expected-revision'])) fail('Protocol revision conflict.', 'REPOSITORY_CONFLICT');
+    if (parsed.subcommand === 'retire') {
+      const metadata = { ...current.metadata, status: 'retired', revision: current.metadata.revision + 1, updatedAt: now() };
+      metadata.digest = bodyDigest(metadata, current.body);
+      const source = render(metadata, current.body), record = validateDocument(source, id);
+      atomicWrite(protocolPath(root, id), source, fs, root.identity, current.metadata.digest);
+      return emit(dependencies, parsed, {protocol: publicProtocol(record), message: `Retired protocol '${id}'. Existing runs require a new reviewed proposal.`});
+    }
+    const body = canonicalBody(readBounded(sourcePath(root, parsed.flags.from, fs), fs, 'Protocol update source'));
+    if (parsed.flags.publish === true) requireProtocolCompleteness(body);
+    const heading = body.match(/^#\s+(\S.*)$/m);
+    if (!heading) fail('Protocol update source must contain a Markdown heading.');
+    const metadata = { ...current.metadata, title: safeText(heading[1].trim(), 120, 'Protocol title'), status: parsed.flags.publish === true ? 'active' : 'draft', revision: current.metadata.revision + 1, updatedAt: now() };
+    metadata.digest = bodyDigest(metadata, body);
+    const source = render(metadata, body);
+    const record = validateDocument(source, id);
+    atomicWrite(protocolPath(root, id), source, fs, root.identity, current.metadata.digest);
+    return emit(dependencies, parsed, { protocol: publicProtocol(record), message: `Updated protocol '${id}'.${metadata.status === 'draft' ? ' ' + draftGuidance(id, metadata.revision) : ''}` });
+  } catch (error) {
+    const safe = error instanceof CliError ? error : new CliError('Protocol operation could not complete safely.', 'INTERNAL_ERROR');
+    return emit(dependencies, parsed ?? input, errorResult(safe), safe.exitCode);
+  }
+}
+
+export function activeProtocolContextRefs(projectRoot, options = {}) {
+  const fs = options.fs ?? filesystem;
+  const root = protocolRoot(resolve(projectRoot), fs);
+  return Object.freeze(discover(root, fs, false, false).map(record => (
+    `protocol:${record.metadata.id}:${record.metadata.revision}:${record.metadata.digest}`
+  )));
+}
+
+export { MAX_PROTOCOL_BYTES, PROTOCOL_DIRECTORY, validateDocument };

package/src/commands/repositories.js

@@ -0,0 +1,77 @@
+import { gitExecutable, resolveConfiguredProject } from '../cli/project-discovery.js';
+import { runArgv } from '../discovery/tools.js';
+import { CliError, EXIT_CODES } from '../cli/output.js';
+import { createNodeProviderTransport } from '../adapters/node-transport.js';
+import { createRepositoryProvider, discoverRepositoryRemotes, selectConfiguredRepositoryRemote } from '../repositories/index.js';
+
+const ENDPOINTS = Object.freeze({github:'https://api.github.com',bitbucket:'https://api.bitbucket.org/2.0',gitlab:'https://gitlab.com/api/v4'});
+const ENV_NAME = /^[A-Z][A-Z0-9_]{1,127}$/;
+function fail(message, code) { throw new CliError(message, code); }
+
+function selectProvider(config, repository, flags) {
+  const candidates = config.providers.providers.filter(provider => provider.kind === 'git-ci'
+    && provider.mode !== 'disabled' && (provider.transport ?? 'direct-api') === 'direct-api'
+    && provider.capabilities.includes('repository-read')
+    && (flags.review === undefined || provider.capabilities.includes('checks-read'))
+    && (!provider.projectIds?.length || provider.projectIds.includes(config.project.id))
+    && (!provider.resourceIds?.length || provider.resourceIds.includes(repository.fullName))
+    && typeof provider.endpoint === 'string'
+    && provider.endpoint.replace(/\/$/,'') === ENDPOINTS[repository.provider]
+    && (flags.provider === undefined || provider.id === flags.provider));
+  if (candidates.length !== 1) fail('Configure one applicable git-ci provider with repository-read, the correct API endpoint and repository scope. Review inspection also requires checks-read. Use --provider=<id> when several match.', 'MISSING_CONFIGURATION');
+  return candidates[0];
+}
+
+function headers(provider, environment) {
+  const credentials = provider.credentials ?? {};
+  const keys = Object.keys(credentials);
+  if (keys.length !== 1 || !['tokenEnv','accessTokenEnv','apiTokenEnv'].includes(keys[0])
+    || !ENV_NAME.test(credentials[keys[0]])) {
+    fail('Configure one token environment reference for repository reads.', 'MISSING_CONFIGURATION');
+  }
+  const token = environment[credentials[keys[0]]];
+  if (typeof token !== 'string' || !token || token.length > 8192 || /[\s\u0000-\u001f\u007f]/.test(token)) {
+    fail('The configured repository token is missing or invalid. Set its environment variable and retry.', 'PROVIDER_UNAVAILABLE');
+  }
+  // This CLI accepts bearer credentials only; it never reads host application credentials.
+  return {authorization:`Bearer ${token}`,accept:'application/json'};
+}
+
+export async function repositoriesCommand(parsed, dependencies) {
+  const {subcommand,operands,flags} = parsed;
+  if(subcommand !== 'inspect' || operands.length
+    || Object.keys(flags).some(key=>!['project','json','remote','provider','review'].includes(key))
+    || (flags.review !== undefined && (!/^[1-9][0-9]{0,8}$/.test(flags.review)))
+    || (flags.provider !== undefined && !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(flags.provider))) {
+    fail('Use rivet repositories inspect [--review=<number>] [--remote=<name>] [--provider=<id>] [--project=<path>] [--json].','INVALID_INPUT');
+  }
+  const project = await resolveConfiguredProject(dependencies.cwd(),flags.project,{runner:dependencies.runGit,env:dependencies.env});
+  let repository;
+  try {
+    const executable = await gitExecutable(dependencies.env);
+    const runner = (_command, args, options) => (dependencies.runGit ?? runArgv)(executable, args, options);
+    const remotes = await (dependencies.repositories?.discoverRemotes ?? discoverRepositoryRemotes)(project.root, {runner});
+    repository = selectConfiguredRepositoryRemote(remotes, project.config.project.repository.remote, flags.remote);
+  } catch {
+    fail('Repository remote is missing, ambiguous, changed or unsupported. Review setup --remote=<name>, or choose a GitHub.com, Bitbucket Cloud or GitLab.com remote with --remote=<name>.','REPOSITORY_CONFLICT');
+  }
+  const provider = selectProvider(project.config,repository,flags);
+  const auth = headers(provider,dependencies.env);
+  let data;
+  try {
+    const adapter = createRepositoryProvider({repository,headers:auth,
+      transport:dependencies.repositories?.transport ?? createNodeProviderTransport()});
+    data = flags.review === undefined ? await adapter.read({kind:'repository'}) : await adapter.inspect({number:Number(flags.review)});
+  } catch(error) {
+    if(error?.code === 'ERR_PROVIDER_STATE_CONFLICT') fail('The review head changed during inspection. Retry to capture a consistent snapshot.','REPOSITORY_CONFLICT');
+    fail('Repository inspection failed. Check token access, repository or review existence, rate limits and provider availability.','PROVIDER_UNAVAILABLE');
+  }
+  const result = {repository,providerId:provider.id,networkChecked:true,observation:data};
+  if(flags.json) dependencies.output.json({ok:true,result});
+  else {
+    dependencies.output.log(`${repository.fullName} (${repository.provider}, remote ${repository.remoteName})`);
+    dependencies.output.log(JSON.stringify(data,null,2).replace(/[\u0000-\u0008\u000b-\u001f\u007f\u009b]/g,c=>`\\u${c.codePointAt(0).toString(16).padStart(4,'0')}`));
+    dependencies.output.log('Read-only observation. This does not authorize merge or deployment.');
+  }
+  return EXIT_CODES.SUCCESS;
+}

package/src/commands/setup-remote.js

@@ -0,0 +1,41 @@
+import { CliError } from '../cli/output.js';
+import { discoverGit } from '../discovery/git.js';
+import { discoverRepositoryRemotes, parseRepositoryRemote, selectConfiguredRepositoryRemote } from '../repositories/index.js';
+import { defaultIntegrationSetupPrompt } from '../cli/integration-setup-prompt.js';
+
+const failure = () => new CliError('Repository remote is missing, ambiguous or changed. Review local Git remotes and use setup --remote=<name> to select the intended repository.', 'REPOSITORY_CONFLICT');
+export async function prepareSetupRemote(root, flags, dependencies, preference) {
+  const read = async () => {
+    const git = await (dependencies.gitDiscovery ?? discoverGit)(root,{runner:dependencies.runner});
+    if (!git.repository) return [];
+    try { return await (dependencies.repositories?.discoverRemotes ?? discoverRepositoryRemotes)(root,{runner:dependencies.runner}); }
+    catch { throw failure(); }
+  };
+  const remotes = await read();
+  const choices = remotes.flatMap(remote => {
+    try { const selected=selectConfiguredRepositoryRemote([remote]);return [{name:selected.remoteName,url:selected.url}]; }
+    catch { return []; }
+  });
+  let selected;
+  if (flags.remote !== undefined || preference) {
+    try { const found=selectConfiguredRepositoryRemote(remotes,preference,flags.remote);selected={name:found.remoteName,url:found.url}; }
+    catch { throw failure(); }
+  } else if (choices.length === 1) selected=choices[0];
+  else if (choices.length > 1 && flags.write) {
+    if (flags.json || !(dependencies.terminalIsInteractive?.() ?? false)) throw failure();
+    const prompt=dependencies.setupRemotePrompt ?? defaultIntegrationSetupPrompt;
+    const name=await prompt({type:'select',message:'Choose the repository remote for inspection and delivery:',choices:choices.map(choice=>({value:choice.name,label:`${choice.name}: ${choice.url}`}))});
+    selected=choices.find(choice=>choice.name===name);
+    if (!selected) throw new CliError('Repository selection cancelled. No setup files were written.','REPOSITORY_CONFLICT');
+  }
+  const verify = async () => {
+    const current=await read();
+    if (selected) {
+      try { selectConfiguredRepositoryRemote(current,selected); } catch { throw failure(); }
+    } else {
+      const safe=current.flatMap(remote=>{try{return [{name:remote.name,url:parseRepositoryRemote(remote.url).url}];}catch{return [];}});
+      if (JSON.stringify(safe)!==JSON.stringify(choices)) throw failure();
+    }
+  };
+  return {selected,choices,status:selected?'selected':choices.length?'selection-required':'local-only',verify};
+}

package/src/commands/setup.js

@@ -0,0 +1,214 @@
+import * as filesystem from 'node:fs';
+import { resolve, join } from 'node:path';
+
+import { CliError, EXIT_CODES } from '../cli/output.js';
+import { loadProjectConfig } from '../config/load.js';
+import { prepareSetupRemote } from './setup-remote.js';
+import { init, prepareRepositoryRemoteUpdate } from './init.js';
+import { inspectManagedInstall, managedInstall } from '../install/managed.js';
+import {parseCheckCommand} from '../discovery/portable.js';
+import {defaultIntegrationSetupPrompt} from '../cli/integration-setup-prompt.js';
+
+const CONFIG_FILES = ['project.yaml', 'providers.yaml', 'orchestration.yaml', 'quality.yaml'];
+
+function emit(parsed, dependencies, result, code = EXIT_CODES.SUCCESS) {
+  if (parsed.flags.json) dependencies.output.json(result, code === 0 ? 'stdout' : 'stderr');
+  else {
+    const write = code === 0 ? dependencies.output.log : dependencies.output.error;
+    write(result.message);
+    for (const action of result.nextSteps ?? []) write(`  ${action}`);
+  }
+  return code;
+}
+
+async function captured(operation, parsed, dependencies) {
+  let value;
+  const code = await operation({ ...parsed, flags: { ...parsed.flags, json: true } }, {
+    ...dependencies,
+    output: { json: payload => { value = payload; }, log() {}, error() {} },
+  });
+  return { code, value };
+}
+
+async function existingConfiguration(root, fs) {
+  const path = join(root, '.rivet');
+  const entry = fs.lstatSync(path, { throwIfNoEntry: false });
+  if (!entry) return false;
+  if (!entry.isDirectory() || entry.isSymbolicLink()) {
+    throw new CliError('Project .rivet configuration must be a regular directory.', 'REPOSITORY_CONFLICT');
+  }
+  // A partially initialized directory needs explicit repair, never automatic replacement.
+  if (!CONFIG_FILES.every(name => {
+    const file = fs.lstatSync(join(path, name), { throwIfNoEntry: false });
+    return file?.isFile() && !file.isSymbolicLink();
+  })) throw new CliError('Existing .rivet configuration is incomplete. Repair it before running setup; no files were replaced.', 'REPOSITORY_CONFLICT');
+  try { await loadProjectConfig(root, { fs }); }
+  catch { throw new CliError('Existing .rivet configuration is invalid. Repair it before running setup; no files were replaced.', 'REPOSITORY_CONFLICT'); }
+  return true;
+}
+
+function previewSteps(preview) {
+  if (!preview?.proposal?.commands) return [];
+  const gates = new Map((preview.proposal.qualityGates ?? [])
+    .map(gate => [gate.command, gate.required ? 'required' : 'optional']));
+  const commands=Object.entries(preview.proposal.commands).flatMap(([logicalId, command]) => {
+    const steps = Array.isArray(command) ? [{ cwd: '.', argv: command }] : command.steps;
+    return steps.map((step, index) => {
+      const prefix = Array.isArray(command)
+        ? `project.commands.${logicalId}` : `project.commands.${logicalId}.steps[${index}]`;
+      const source = preview.proposal.provenance?.[`${prefix}.cwd`]?.source
+        ?? preview.proposal.provenance?.[`${prefix}[0]`]?.source
+        ?? preview.proposal.provenance?.[prefix]?.source
+        ?? 'unavailable';
+      return `${logicalId} (${gates.get(logicalId) ?? 'not-gated'}): ${step.cwd} -> ${step.argv.join(' ')} [source: ${source}]`;
+    });
+  });
+  const installation=preview.proposal.dependencies;
+  if(installation) {
+    commands.push(`Dependency inputs: ${JSON.stringify(installation.inputs)}. Installation requires separate approval.`);
+    for(const step of installation.steps)commands.push(`Dependency install: ${JSON.stringify(step.cwd)} -> ${JSON.stringify(step.argv)}`);
+  }
+  return commands;
+}
+
+export async function setupCommand(parsed, dependencies) {
+  const flags = parsed.flags;
+  if (parsed.operands.length || parsed.subcommand !== null
+    || Object.keys(flags).some(key => !['project', 'global', 'target', 'write', 'json', 'remote', 'checks-json', 'dependencies-json'].includes(key))
+    || (flags.global && (flags.project !== undefined || flags.remote !== undefined || flags['checks-json'] !== undefined || flags['dependencies-json'] !== undefined))
+    || (flags.target !== undefined && !['claude', 'codex', 'both'].includes(flags.target))) {
+    throw new CliError('Use rivet setup [--project=<path>|--global] [--remote=<name>] [--target=claude|codex|both] [--write].', 'INVALID_INPUT');
+  }
+  const fs = dependencies.fs ?? filesystem;
+  const root = resolve(dependencies.cwd(), flags.project ?? '.');
+  const target = flags.target ?? 'both';
+  const projectArgument = root === resolve(dependencies.cwd()) ? ''
+    : ` --project='${root.replaceAll("'", "'\"'\"'")}'`;
+  const installer = { command: 'install', subcommand: null, operands: [], flags: {
+    minimal: true, target, ...(flags.global ? { global: true } : { project: root }),
+  } };
+  const services = dependencies.setup ?? {};
+  const inspect = services.inspectInstall ?? inspectManagedInstall;
+  const install = services.install ?? managedInstall;
+  const initialize = services.init ?? init;
+  // Preflight every install destination before creating any project configuration.
+  const installation = await inspect(installer, dependencies);
+  let configuration = { status: 'not-applicable' };
+  let preview, remote, remoteUpdate;
+  let checks = flags['checks-json'];
+  const installFlags=flags['dependencies-json']===undefined?{}:{'dependencies-json':flags['dependencies-json']};
+  if (!flags.global) {
+    const retained = await existingConfiguration(root, fs);
+    if(retained && (checks!==undefined || flags['dependencies-json']!==undefined)) throw new CliError('Existing configuration was preserved. Review and edit commands in .rivet/project.yaml and gates in .rivet/quality.yaml to change existing checks or dependency installation.','INVALID_INPUT');
+    const existing = retained ? await loadProjectConfig(root, {fs}) : null;
+    remote = await prepareSetupRemote(root, flags, dependencies, existing?.project.repository.remote);
+    if (retained) {
+      configuration = { status: 'preserved' };
+      if (remote.selected && JSON.stringify(remote.selected) !== JSON.stringify(existing.project.repository.remote)) {
+        const transaction = await prepareRepositoryRemoteUpdate(root, {fs, beforeCommit:remote.verify});
+        remoteUpdate = transaction.propose(remote.selected);
+        configuration = {status:'remote-proposed', projectYaml:remoteUpdate.yaml};
+      }
+    }
+    else {
+      preview = await captured(initialize, {
+        command: 'init', subcommand: null, operands: [], flags: { project: root, ...installFlags, ...(checks!==undefined?{'checks-json':checks}:{}) },
+      }, {...dependencies,setupRemoteSelection:remote});
+      if(preview.code===EXIT_CODES.MISSING_CONFIGURATION && checks===undefined && flags.write && !flags.json && dependencies.terminalIsInteractive?.()) {
+        const answer=await (dependencies.projectChecksPrompt??defaultIntegrationSetupPrompt)({type:'input',message:'No checks were detected. Enter this project’s verification command (for example python3 -m pytest; no shell chaining):'});
+        if(answer) {
+          try {checks=JSON.stringify({test:parseCheckCommand(answer)});}
+          catch(error) {throw new CliError(error.message,'INVALID_INPUT');}
+          preview=await captured(initialize,{command:'init',subcommand:null,operands:[],flags:{project:root,...installFlags,'checks-json':checks}}, {...dependencies,setupRemoteSelection:remote});
+        }
+      }
+      if (preview.code !== 0) return emit(parsed, dependencies, {
+        ok: false, status: 'blocked', message: preview.value?.error?.message ?? 'Project discovery failed. No setup files were written.',
+        configuration: preview.value,
+        nextSteps: [`Run rivet init${projectArgument} --json for configuration diagnostics.`],
+      }, preview.code);
+      configuration = { ...preview.value, status: 'proposed' };
+    }
+  }
+  const missingScripts = preview?.value.discovery.unresolved?.map(item => item.command) ?? [];
+  const tools = preview?.value.discovery.tools;
+  const missingTools = tools ? ['node', 'git', ...Object.keys(tools).filter(key => ['npm', 'pnpm', 'yarn', 'bun'].includes(key))]
+    .filter(name => !tools[name]?.present || (name === 'node' && Number.parseInt(tools.node.version, 10) < 22)) : [];
+  const blockers = [
+    ...missingTools.map(name => `Install ${name === 'node' ? 'Node.js 22 or newer' : name} and make it available on PATH.`),
+  ];
+  const warnings = [
+    ...missingScripts.map(name => `No '${name}' package script was detected in the supported root/immediate-child scope. Add one before relying on this required check.`),
+    ...(preview?.value.discovery.warnings ?? []).map(item => item.message),
+  ];
+  const result = {
+    ok: true, status: 'preview', scope: flags.global ? 'global' : 'project', target,
+    configuration, installation, blockers, warnings,
+    ...(remote ? {repository:{status:remote.status,selected:remote.selected??null,choices:remote.choices}} : {}),
+    message: 'Setup preview: no files were written.',
+    nextSteps: blockers.length ? [...blockers, ...warnings] : [
+      ...warnings,
+      ...(!flags.global && preview ? [
+        `Project configuration: ${CONFIG_FILES.map(name => join(root, '.rivet', name)).join(', ')}`,
+        ...previewSteps(preview.value),
+        'Checks have not run; setup only inspected bounded project metadata.',
+      ] : []),
+      ...(installation.targets ?? installation.result?.targets ?? [])
+        .map(entry => `${entry.target} skill: ${entry.skillDir} (${entry.action})`),
+      ...(remote?.choices.length ? remote.choices.map(choice=>`${remote.selected?.name === choice.name ? 'Selected repository remote' : 'Available repository remote'}: ${choice.name} -> ${choice.url}`) : []),
+      ...(remote?.status === 'selection-required' ? ['Choose a repository with --remote=<name> when applying setup.'] : []),
+      'Repeat with --write to apply this setup.',
+    ],
+  };
+  if (!flags.write) return emit(parsed, dependencies, result);
+  if (blockers.length) return emit(parsed, dependencies, {
+    ...result, ok: false, status: 'blocked', message: 'Resolve the setup checks before writing configuration.',
+  }, EXIT_CODES.FAILED_GATE);
+  await remote?.verify();
+  let configurationWritten = false;
+  if (remoteUpdate) {
+    const cleanup = await remoteUpdate.commit();
+    configuration = {status:'remote-written',cleanup};
+    configurationWritten = true;
+  }
+  if (preview) {
+    const written = await captured(initialize, {
+      command: 'init', subcommand: null, operands: [], flags: { project: root, write: true, ...installFlags, ...(checks!==undefined?{'checks-json':checks}:{}) },
+    }, {...dependencies,setupRemoteSelection:remote});
+    if (written.code !== 0) return emit(parsed, dependencies, {
+      ...result, ok: false, status: 'blocked', configuration: written.value,
+      message: 'Configuration could not be written safely; harness installation was not started.',
+    }, written.code);
+    configuration = { ...written.value, status: 'written' };
+    configurationWritten = true;
+  }
+  try {
+    const installed = await captured(install, installer, dependencies);
+    if (installed.code !== 0) throw new CliError('Harness installation did not complete.', 'REPOSITORY_CONFLICT');
+    return emit(parsed, dependencies, {
+      ...result, status: 'configured', configuration, installation: installed.value,
+      message: flags.global ? 'Minimal Rivet harness instructions installed globally.' : 'Project configuration and minimal Rivet harness instructions are ready.',
+      nextSteps: [
+        ...warnings,
+        'Reload your harness so it discovers the Rivet skill.',
+        'Ask your harness: "Read the Rivet skill and report this project\'s configured checks."',
+        ...(flags.global ? ['Run rivet setup from each project root to configure that project.'] : [
+          'Review and commit the generated setup files. Confirm repository.defaultBranch in .rivet/project.yaml and switch to that branch before starting a task.',
+          `Run rivet doctor${projectArgument} to inspect configured readiness.`,
+          `Optionally run rivet integrations setup${projectArgument} to guide read-only tracker and context configuration.`,
+          `Run rivet preflight --mode=host${projectArgument} before starting a task.`,
+        ]),
+        'This configures instructions and policy; model authentication and active-harness execution are separate.',
+      ],
+    });
+  } catch (error) {
+    const denied = error instanceof CliError && error.code === 'BLOCKED_AUTHORITY';
+    return emit(parsed, dependencies, {
+      ok: false, status: configurationWritten ? 'partial' : 'blocked', configurationWritten,
+      message: denied ? error.safeMessage : 'Harness installation stopped. Existing files and any newly written project configuration are preserved.',
+      ...(denied ? { error: { code: error.code, exitCode: error.exitCode, message: error.safeMessage } } : {}),
+      nextSteps: denied ? ['Existing project configuration is preserved. After normal permission approval, rerun the reviewed setup command.']
+        : ['Resolve the installation conflict, then rerun setup. Inspect rivet install --minimal --json for details.'],
+    }, denied ? EXIT_CODES.BLOCKED_AUTHORITY : EXIT_CODES.REPOSITORY_CONFLICT);
+  }
+}