@paulojalowyj/openkit 0.1.1 → 0.2.0

package/README.md

@@ -30,6 +30,19 @@ npx @paulojalowyj/openkit init --blueprint fullstack
 # (restart OpenCode TUI and use / commands)
 ```
 
+## Upgrade
+
+```bash
+# Preview changes (no writes)
+npx @paulojalowyj/openkit upgrade --dry-run
+
+# Apply safe upgrades (non-interactive defaults to skipping conflicts)
+npx @paulojalowyj/openkit upgrade
+
+# CI mode: fail job when customizations/conflicts exist
+npx @paulojalowyj/openkit upgrade --fail-on-changes
+```
+
 ## About OpenCode
 
 OpenCode is a terminal-based AI coding agent that OpenKit uses to execute commands and manage agents.

package/README.pt-BR.md

@@ -29,6 +29,19 @@ npx @paulojalowyj/openkit init --blueprint fullstack
 # (execute `opencode` no seu projeto e use os comandos /)
 ```
 
+## Upgrade
+
+```bash
+# Ver o plano (sem escrever arquivos)
+npx @paulojalowyj/openkit upgrade --dry-run
+
+# Aplicar upgrades seguros (sem TTY, conflitos sao pulados por default)
+npx @paulojalowyj/openkit upgrade
+
+# CI: falhar o job quando houver customizacoes/conflitos
+npx @paulojalowyj/openkit upgrade --fail-on-changes
+```
+
 ## Sobre o OpenCode
 
 OpenCode é um agente de código AI baseado em terminal que o OpenKit usa para executar comandos e gerenciar agentes.

package/bin/cli.js

@@ -4,18 +4,30 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { copyFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'fs';
 import { dirname } from 'path';
 import { execSync } from 'child_process';
 import inquirer from 'inquirer';
 import fs from 'fs-extra';
 import { glob } from 'glob';
+import { writeInitManifest } from './lib/upgrade/init-manifest.js';
+import { runUpgrade } from './lib/upgrade/index.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 const program = new Command();
 
+function getOpenkitVersion() {
+  try {
+    const pkgPath = path.join(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    if (pkg && typeof pkg.version === 'string') return pkg.version;
+  } catch {
+  }
+  return program.version();
+}
+
 function checkOpenCodeInstalled() {
   try {
     execSync('which opencode || where opencode', {
@@ -149,6 +161,10 @@ async function copyDir(src, dest, root = src) {
       continue;
     }
 
+    if (entry.isSymbolicLink()) {
+      throw new Error(`Refusing to copy symlink: ${relativePath}`);
+    }
+
     if (entry.isDirectory()) {
       await copyDir(srcPath, destPath, root);
     } else {
@@ -317,7 +333,31 @@ async function replacePlaceholders(dir, replacements) {
 }
 
 async function copyBlueprint(blueprintName, targetDir, replacements) {
-  const blueprintDir = path.join(__dirname, '..', 'blueprints', blueprintName);
+  const blueprintsRoot = path.join(__dirname, '..', 'blueprints');
+  const availableBlueprints = (() => {
+    try {
+      return readdirSync(blueprintsRoot, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+    } catch {
+      return [];
+    }
+  })();
+
+  if (!blueprintName || typeof blueprintName !== 'string') {
+    throw new Error('Blueprint name is required');
+  }
+
+  if (blueprintName.includes('..') || blueprintName.includes('/') || blueprintName.includes('\\')) {
+    throw new Error('Invalid blueprint name');
+  }
+
+  if (!availableBlueprints.includes(blueprintName)) {
+    const hint = availableBlueprints.length > 0 ? ` Available: ${availableBlueprints.join(', ')}` : '';
+    throw new Error(`Blueprint "${blueprintName}" não encontrado.${hint}`);
+  }
+
+  const blueprintDir = path.join(blueprintsRoot, blueprintName);
 
   if (!existsSync(blueprintDir)) {
     throw new Error(`Blueprint "${blueprintName}" não encontrado`);
@@ -335,7 +375,7 @@ async function copyBlueprint(blueprintName, targetDir, replacements) {
 program
   .name('openkit')
   .description('OpenKit - OpenCode Agent System in your project')
-  .version('0.1.1');
+  .version('0.2.0');
 
 program
   .command('init')
@@ -404,6 +444,8 @@ program
     const templateConfigPath = path.join(__dirname, '..', 'opencode.json');
     const targetConfigPath = path.join(projectDir, 'opencode.json');
 
+    const willWriteRootConfig = existsSync(templateConfigPath) && (!existsSync(targetConfigPath) || options.force);
+
     if (existsSync(templateConfigPath)) {
       if (existsSync(targetConfigPath) && !options.force) {
         console.log(chalk.yellow('Warning: opencode.json already exists, skipping'));
@@ -413,6 +455,20 @@ program
       }
     }
 
+    // Write install manifest for safe upgrades (no extra console noise).
+    try {
+      await writeInitManifest({
+        fs,
+        projectRootAbs: projectDir,
+        templateDirAbs: templateDir,
+        templateRootConfigAbs: templateConfigPath,
+        openkitVersion: getOpenkitVersion(),
+        includeRootConfig: willWriteRootConfig
+      });
+    } catch (e) {
+      console.log(chalk.yellow(`Warning: failed to write manifest (${e.message})`));
+    }
+
     if (options.blueprint) {
       const replacements = {
         '{{PROJECT_NAME}}': metadata.projectName,
@@ -441,6 +497,99 @@ program
     console.log('');
   });
 
+program
+  .command('upgrade')
+  .description('Upgrade OpenCode configuration in current directory')
+  .option('--dry-run', 'Plan changes without writing')
+  .option('--yes', 'Assume defaults (TTY only); conflicts default to skip')
+  .option('--force', 'Overwrite all managed files (with backup)')
+  .option('--overwrite-changed', 'Overwrite customized files (with backup)')
+  .option('--fail-on-changes', 'Exit with code 2 if conflicts/customizations detected')
+  .option('--prune', 'Remove files no longer present in template (with backup)')
+  .option('--manifest-path <path>', 'Override manifest path (relative to project root)')
+  .action(async (options) => {
+    const projectDir = process.cwd();
+    const opencodeDir = path.join(projectDir, '.opencode');
+
+    try {
+      const st = await fs.lstat(opencodeDir);
+      if (st.isSymbolicLink()) throw new Error('.opencode is a symlink');
+      if (!st.isDirectory()) throw new Error('.opencode is not a directory');
+    } catch (e) {
+      if (e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')) {
+        console.log('Missing .opencode directory. Run `openkit init` first.');
+        process.exit(1);
+      }
+      console.log(`Upgrade failed: ${e.message}`);
+      process.exit(1);
+    }
+
+    const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const templateDir = path.join(__dirname, '..', '.opencode');
+    const templateRootConfig = path.join(__dirname, '..', 'opencode.json');
+    const hasTemplateRootConfig = existsSync(templateRootConfig);
+
+    try {
+      const result = await runUpgrade({
+        fs,
+        prompt: inquirer.prompt,
+        projectRootAbs: projectDir,
+        templateDirAbs: templateDir,
+        templateRootConfigAbs: hasTemplateRootConfig ? templateRootConfig : null,
+        openkitVersion: getOpenkitVersion(),
+        options: {
+          dryRun: Boolean(options.dryRun),
+          yes: Boolean(options.yes),
+          force: Boolean(options.force),
+          overwriteChanged: Boolean(options.overwriteChanged),
+          failOnChanges: Boolean(options.failOnChanges),
+          prune: Boolean(options.prune) || Boolean(options.force),
+          manifestPath: options.manifestPath,
+          isInteractive
+        }
+      });
+
+      const { buckets, backupsDir } = result;
+      const counts = {
+        added: buckets.add.length,
+        updated: buckets.update.length,
+        overwritten: buckets.overwrite.length,
+        removed: buckets.remove.length,
+        skipped: buckets.skip.length,
+        conflicts: buckets.conflicts.length,
+        orphaned: buckets.orphaned.length
+      };
+
+      const lines = [];
+      lines.push(`added: ${counts.added}`);
+      lines.push(`updated: ${counts.updated}`);
+      lines.push(`overwritten: ${counts.overwritten}`);
+      lines.push(`removed: ${counts.removed}`);
+      lines.push(`skipped: ${counts.skipped}`);
+      lines.push(`conflicts: ${counts.conflicts}`);
+      lines.push(`orphaned: ${counts.orphaned}`);
+      if (backupsDir) lines.push(`backups: ${backupsDir}`);
+      console.log(lines.join('\n'));
+
+      const shouldListAll = Boolean(options.dryRun);
+      const listBuckets = shouldListAll
+        ? ['add', 'update', 'overwrite', 'remove', 'skip', 'conflicts', 'orphaned']
+        : ['skip', 'conflicts', 'orphaned', 'remove'];
+
+      for (const key of listBuckets) {
+        const arr = buckets[key];
+        if (!arr || arr.length === 0) continue;
+        console.log(`\n${key}:`);
+        for (const p of arr.sort()) console.log(`  ${p}`);
+      }
+
+      process.exit(result.exitCode);
+    } catch (e) {
+      console.log(`Upgrade failed: ${e.message}`);
+      process.exit(1);
+    }
+  });
+
 program
   .command('doctor')
   .description('Check OpenCode installation')

package/bin/lib/upgrade/applier.js

@@ -0,0 +1,87 @@
+import path from 'path';
+import { resolveWithinRoot, assertNoSymlinkInPath } from './paths.js';
+import { sha256Hex } from './sha256.js';
+
+async function existsNoFollow(fs, absPath) {
+  try {
+    const st = await fs.lstat(absPath);
+    return { exists: true, stat: st };
+  } catch (e) {
+    if (e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')) return { exists: false, stat: null };
+    throw e;
+  }
+}
+
+async function ensureParentDir(fs, absPath) {
+  await fs.mkdir(path.dirname(absPath), { recursive: true });
+}
+
+async function writeFileAtomic(fs, absPath, content) {
+  const tmp = `${absPath}.tmp-${sha256Hex(String(Date.now())).slice(0, 8)}`;
+  await fs.writeFile(tmp, content);
+  await fs.rename(tmp, absPath);
+}
+
+async function backupFile({ fs, projectRootAbs, backupsDirAbs, relPath }) {
+  const srcAbs = resolveWithinRoot(projectRootAbs, relPath);
+  const dstAbs = path.join(backupsDirAbs, relPath.replace(/\\/g, '/'));
+  await fs.mkdir(path.dirname(dstAbs), { recursive: true });
+  await fs.copyFile(srcAbs, dstAbs);
+}
+
+export async function applyUpgradeOps({ fs, projectRootAbs, templateFiles, ops, backupsDirRel }) {
+  const modified = [];
+  const removed = [];
+  const added = [];
+
+  const willOverwriteOrRemove = ops.some((op) => op.type === 'update' || op.type === 'overwrite' || op.type === 'remove');
+  const backupsDirAbs = willOverwriteOrRemove ? resolveWithinRoot(projectRootAbs, backupsDirRel) : null;
+  if (backupsDirAbs) {
+    await assertNoSymlinkInPath(fs, projectRootAbs, backupsDirRel);
+    await fs.mkdir(backupsDirAbs, { recursive: true });
+  }
+
+  for (const op of ops) {
+    if (op.type === 'orphaned' || op.type === 'conflict' || op.type === 'skip') continue;
+
+    await assertNoSymlinkInPath(fs, projectRootAbs, op.path);
+    const abs = resolveWithinRoot(projectRootAbs, op.path);
+
+    const { exists, stat } = await existsNoFollow(fs, abs);
+    if (exists && stat.isSymbolicLink()) throw new Error(`Refusing to operate on symlink: ${op.path}`);
+    if (exists && !stat.isFile()) throw new Error(`Refusing to operate on non-file path: ${op.path}`);
+
+    if (op.type === 'remove') {
+      if (exists) {
+        await backupFile({ fs, projectRootAbs, backupsDirAbs, relPath: op.path });
+        await fs.unlink(abs);
+        removed.push(op.path);
+      }
+      continue;
+    }
+
+    const tf = templateFiles.get(op.path);
+    if (!tf) throw new Error(`Missing template content for: ${op.path}`);
+
+    if (op.type === 'add') {
+      await ensureParentDir(fs, abs);
+      await writeFileAtomic(fs, abs, tf.content);
+      added.push(op.path);
+      continue;
+    }
+
+    if (op.type === 'update' || op.type === 'overwrite') {
+      if (exists) await backupFile({ fs, projectRootAbs, backupsDirAbs, relPath: op.path });
+      await ensureParentDir(fs, abs);
+      await writeFileAtomic(fs, abs, tf.content);
+      modified.push(op.path);
+    }
+  }
+
+  return {
+    backupsDir: backupsDirAbs ? backupsDirRel : null,
+    added,
+    modified,
+    removed
+  };
+}

package/bin/lib/upgrade/index.js

@@ -0,0 +1,215 @@
+import path from 'path';
+import { sha256Hex } from './sha256.js';
+import { resolveWithinRoot, assertNoSymlinkInPath } from './paths.js';
+import { readTemplateFiles } from './template.js';
+import { loadManifestIfExists, writeManifest, createEmptyManifest, defaultDecision, upsertManifestFile, indexManifestFiles } from './manifest.js';
+import { planUpgrade } from './planner.js';
+import { applyUpgradeOps } from './applier.js';
+
+async function readProjectFileState({ fs, projectRootAbs, relPath }) {
+  await assertNoSymlinkInPath(fs, projectRootAbs, relPath);
+  const abs = resolveWithinRoot(projectRootAbs, relPath);
+  try {
+    const st = await fs.lstat(abs);
+    if (st.isSymbolicLink()) throw new Error(`Refusing to read through symlink: ${relPath}`);
+    if (!st.isFile()) throw new Error(`Expected file but found non-file: ${relPath}`);
+    const buf = await fs.readFile(abs);
+    return { exists: true, currentSha256: sha256Hex(buf) };
+  } catch (e) {
+    if (e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')) return { exists: false, currentSha256: null };
+    throw e;
+  }
+}
+
+async function projectHasRegularFileNoFollow({ fs, projectRootAbs, relPath }) {
+  await assertNoSymlinkInPath(fs, projectRootAbs, relPath);
+  const abs = resolveWithinRoot(projectRootAbs, relPath);
+  try {
+    const st = await fs.lstat(abs);
+    if (st.isSymbolicLink()) return false;
+    return st.isFile();
+  } catch (e) {
+    if (e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')) return false;
+    throw e;
+  }
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function backupsDirRelFromNow() {
+  const safe = nowIso().replace(/[:.]/g, '-');
+  return `.opencode/.openkit-backups/openkit-upgrade-${safe}`;
+}
+
+function summarizeOps(ops) {
+  const buckets = {
+    add: [],
+    update: [],
+    overwrite: [],
+    remove: [],
+    skip: [],
+    conflict: [],
+    orphaned: []
+  };
+
+  for (const op of ops) {
+    if (buckets[op.type]) buckets[op.type].push(op.path);
+    else if (op.type === 'conflict') buckets.conflict.push(op.path);
+  }
+
+  return buckets;
+}
+
+export async function runUpgrade({
+  fs,
+  prompt,
+  projectRootAbs,
+  templateDirAbs,
+  templateRootConfigAbs,
+  openkitVersion,
+  options
+}) {
+  const manifestRelPath = options.manifestPath || '.opencode/openkit.manifest.json';
+  const existingManifest = await loadManifestIfExists({ fs, projectRootAbs, manifestRelPath });
+
+  const rootConfigExists = await projectHasRegularFileNoFollow({ fs, projectRootAbs, relPath: 'opencode.json' });
+
+  const manageRootConfig = Boolean(
+    templateRootConfigAbs &&
+    (options.force || !rootConfigExists || (existingManifest && existingManifest.managedPaths.includes('opencode.json')))
+  );
+
+  const templateFiles = await readTemplateFiles({
+    fs,
+    templateDirAbs,
+    includeRootConfig: manageRootConfig,
+    rootConfigPathAbs: templateRootConfigAbs
+  });
+
+  const projectFileStates = new Map();
+  for (const relPath of templateFiles.keys()) {
+    projectFileStates.set(relPath, await readProjectFileState({ fs, projectRootAbs, relPath }));
+  }
+
+  const ops = planUpgrade({
+    templateFiles,
+    manifest: existingManifest,
+    projectFileStates,
+    options: {
+      ...options,
+      isInteractive: Boolean(options.isInteractive)
+    }
+  });
+
+  // Resolve interactive conflicts (only those still marked as 'conflict').
+  if (options.isInteractive && !options.yes) {
+    for (const op of ops) {
+      if (op.type !== 'conflict') continue;
+
+      const question = {
+        type: 'confirm',
+        name: 'overwrite',
+        message: `Arquivo modificado: ${op.path}. Sobrescrever com o template?`,
+        default: false
+      };
+
+      const rememberQ = {
+        type: 'confirm',
+        name: 'remember',
+        message: 'Lembrar esta decisao para proximos upgrades?',
+        default: true
+      };
+
+      const ans = await prompt([question, rememberQ]);
+      op.type = ans.overwrite ? 'overwrite' : 'skip';
+      op.reason = op.reason || 'conflict';
+      op._remember = Boolean(ans.remember);
+      op._rememberChoice = ans.overwrite ? 'overwrite' : 'skip';
+    }
+  }
+
+  const buckets = summarizeOps(ops);
+  const conflicts = ops
+    .filter((op) => op && (op.reason === 'conflict' || op.reason === 'legacy-conflict'))
+    .map((op) => op.path);
+
+  const exitCode = options.failOnChanges && conflicts.length > 0 ? 2 : 0;
+
+  if (options.dryRun) {
+    return {
+      didWrite: false,
+      exitCode,
+      buckets: { ...buckets, conflicts },
+      backupsDir: null
+    };
+  }
+
+  const applyResult = await applyUpgradeOps({
+    fs,
+    projectRootAbs,
+    templateFiles,
+    ops,
+    backupsDirRel: backupsDirRelFromNow()
+  });
+
+  // Manifest update (best-effort baseline tracking).
+  const installedAt = existingManifest ? existingManifest.installedAt : nowIso();
+  const manifest = existingManifest || createEmptyManifest({
+    openkitVersion,
+    installedAtIso: installedAt,
+    managedPaths: manageRootConfig ? ['.opencode', 'opencode.json'] : ['.opencode']
+  });
+
+  manifest.openkitVersion = openkitVersion;
+  if (!manifest.managedPaths.includes('.opencode')) manifest.managedPaths.unshift('.opencode');
+  if (manageRootConfig && !manifest.managedPaths.includes('opencode.json')) manifest.managedPaths.push('opencode.json');
+
+  const mfIndex = indexManifestFiles(manifest);
+  for (const [relPath, tf] of templateFiles.entries()) {
+    const existing = mfIndex.get(relPath);
+    const op = ops.find((o) => o.path === relPath);
+    const applied = op && (op.type === 'add' || op.type === 'update' || op.type === 'overwrite');
+
+    const next = existing ? { ...existing } : {
+      path: relPath,
+      kind: tf.kind,
+      baseSha256: tf.templateSha256,
+      lastAppliedOpenkitVersion: openkitVersion,
+      decision: defaultDecision()
+    };
+
+    if (applied) {
+      next.baseSha256 = tf.templateSha256;
+      next.lastAppliedOpenkitVersion = openkitVersion;
+    }
+
+    if (op && op._remember && next.decision && next.decision.remember) {
+      next.decision.onConflict = op._rememberChoice;
+    }
+
+    upsertManifestFile(manifest, next);
+  }
+
+  // Orphaned cleanup in manifest only if removed.
+  if (applyResult.removed.length > 0) {
+    const removedSet = new Set(applyResult.removed);
+    manifest.files = manifest.files.filter((f) => !(f && removedSet.has(f.path)));
+  }
+
+  manifest.history.push({
+    type: 'upgrade',
+    openkitVersion,
+    timestamp: nowIso()
+  });
+
+  await writeManifest({ fs, projectRootAbs, manifestRelPath, manifest });
+
+  return {
+    didWrite: true,
+    exitCode,
+    buckets: { ...buckets, conflicts },
+    backupsDir: applyResult.backupsDir
+  };
+}

package/bin/lib/upgrade/init-manifest.js

@@ -0,0 +1,47 @@
+import { readTemplateFiles } from './template.js';
+import { createEmptyManifest, defaultDecision, upsertManifestFile, writeManifest } from './manifest.js';
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+export async function writeInitManifest({
+  fs,
+  projectRootAbs,
+  templateDirAbs,
+  templateRootConfigAbs,
+  openkitVersion,
+  includeRootConfig,
+  manifestRelPath = '.opencode/openkit.manifest.json'
+}) {
+  const templateFiles = await readTemplateFiles({
+    fs,
+    templateDirAbs,
+    includeRootConfig,
+    rootConfigPathAbs: templateRootConfigAbs
+  });
+
+  const manifest = createEmptyManifest({
+    openkitVersion,
+    installedAtIso: nowIso(),
+    managedPaths: includeRootConfig ? ['.opencode', 'opencode.json'] : ['.opencode']
+  });
+
+  for (const [relPath, tf] of templateFiles.entries()) {
+    upsertManifestFile(manifest, {
+      path: relPath,
+      kind: tf.kind,
+      baseSha256: tf.templateSha256,
+      lastAppliedOpenkitVersion: openkitVersion,
+      decision: defaultDecision()
+    });
+  }
+
+  manifest.history.push({
+    type: 'init',
+    openkitVersion,
+    timestamp: nowIso()
+  });
+
+  await writeManifest({ fs, projectRootAbs, manifestRelPath, manifest });
+}

package/bin/lib/upgrade/manifest.js

@@ -0,0 +1,86 @@
+import { sha256Hex } from './sha256.js';
+import { resolveWithinRoot, assertNoSymlinkInPath } from './paths.js';
+import path from 'path';
+
+export function createEmptyManifest({ openkitVersion, installedAtIso, managedPaths }) {
+  return {
+    schemaVersion: 1,
+    managedBy: '@paulojalowyj/openkit',
+    openkitVersion,
+    installedAt: installedAtIso,
+    projectRoot: '.',
+    managedPaths,
+    files: [],
+    history: []
+  };
+}
+
+export function validateManifest(manifest) {
+  if (!manifest || typeof manifest !== 'object') throw new Error('Invalid manifest: not an object');
+  if (manifest.schemaVersion !== 1) throw new Error(`Unsupported manifest schemaVersion: ${manifest.schemaVersion}`);
+  if (manifest.managedBy !== '@paulojalowyj/openkit') throw new Error('Invalid manifest: managedBy mismatch');
+  if (!Array.isArray(manifest.files)) throw new Error('Invalid manifest: files must be an array');
+  if (!Array.isArray(manifest.history)) throw new Error('Invalid manifest: history must be an array');
+  if (!Array.isArray(manifest.managedPaths)) throw new Error('Invalid manifest: managedPaths must be an array');
+}
+
+export async function loadManifestIfExists({ fs, projectRootAbs, manifestRelPath }) {
+  await assertNoSymlinkInPath(fs, projectRootAbs, manifestRelPath);
+  const abs = resolveWithinRoot(projectRootAbs, manifestRelPath);
+  try {
+    const st = await fs.lstat(abs);
+    if (st.isSymbolicLink()) throw new Error('Refusing to read manifest through symlink');
+    if (!st.isFile()) throw new Error('Manifest path exists but is not a file');
+  } catch (e) {
+    if (e && (e.code === 'ENOENT' || e.code === 'ENOTDIR')) return null;
+    throw e;
+  }
+
+  const raw = await fs.readFile(abs, 'utf8');
+  const parsed = JSON.parse(raw);
+  validateManifest(parsed);
+  return parsed;
+}
+
+export async function writeManifest({ fs, projectRootAbs, manifestRelPath, manifest }) {
+  validateManifest(manifest);
+
+  const abs = resolveWithinRoot(projectRootAbs, manifestRelPath);
+  await assertNoSymlinkInPath(fs, projectRootAbs, manifestRelPath);
+
+  try {
+    const st = await fs.lstat(abs);
+    if (st.isSymbolicLink()) throw new Error('Refusing to write manifest to symlink path');
+  } catch (e) {
+    if (!e || (e.code !== 'ENOENT' && e.code !== 'ENOTDIR')) throw e;
+  }
+
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+
+  const tmp = `${abs}.tmp-${sha256Hex(String(Date.now())).slice(0, 8)}`;
+  const json = JSON.stringify(manifest, null, 2) + '\n';
+  await fs.writeFile(tmp, json, 'utf8');
+  await fs.rename(tmp, abs);
+}
+
+export function indexManifestFiles(manifest) {
+  const byPath = new Map();
+  for (const f of manifest.files || []) {
+    if (f && typeof f.path === 'string') byPath.set(f.path, f);
+  }
+  return byPath;
+}
+
+export function upsertManifestFile(manifest, fileEntry) {
+  const idx = (manifest.files || []).findIndex((f) => f && f.path === fileEntry.path);
+  if (idx === -1) manifest.files.push(fileEntry);
+  else manifest.files[idx] = fileEntry;
+}
+
+export function defaultDecision() {
+  return {
+    strategy: 'follow-template',
+    onConflict: 'prompt',
+    remember: true
+  };
+}

package/bin/lib/upgrade/paths.js

@@ -0,0 +1,55 @@
+import path from 'path';
+
+function toPosixPath(p) {
+  return String(p).replace(/\\/g, '/');
+}
+
+export function normalizeRelPath(inputPath) {
+  const p = toPosixPath(inputPath);
+  if (p.includes('\u0000')) throw new Error('Invalid path: contains null byte');
+  if (path.posix.isAbsolute(p)) throw new Error(`Invalid path: absolute path not allowed (${inputPath})`);
+
+  const normalized = path.posix.normalize(p);
+  if (normalized === '.' || normalized === '') return '';
+  if (normalized.startsWith('../') || normalized === '..') {
+    throw new Error(`Invalid path: path traversal not allowed (${inputPath})`);
+  }
+  return normalized;
+}
+
+export function resolveWithinRoot(projectRootAbs, relPath) {
+  const root = path.resolve(projectRootAbs);
+  const rel = normalizeRelPath(relPath);
+  const abs = path.resolve(root, rel);
+  const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep;
+  if (abs !== root && !abs.startsWith(rootWithSep)) {
+    throw new Error(`Path escapes project root: ${relPath}`);
+  }
+  return abs;
+}
+
+export async function assertNoSymlinkInPath(fs, projectRootAbs, relPath) {
+  const root = path.resolve(projectRootAbs);
+  const rel = normalizeRelPath(relPath);
+  if (!rel) return;
+
+  const parts = rel.split('/');
+  let cursor = root;
+
+  for (const part of parts.slice(0, -1)) {
+    cursor = path.join(cursor, part);
+    let st;
+    try {
+      st = await fs.lstat(cursor);
+    } catch {
+      // Missing directories will be created later; we only guard existing ones.
+      continue;
+    }
+    if (st.isSymbolicLink()) {
+      throw new Error(`Refusing to traverse symlinked directory: ${path.relative(root, cursor)}`);
+    }
+    if (!st.isDirectory()) {
+      throw new Error(`Expected directory but found file: ${path.relative(root, cursor)}`);
+    }
+  }
+}

package/bin/lib/upgrade/planner.js

@@ -0,0 +1,67 @@
+import { indexManifestFiles, defaultDecision } from './manifest.js';
+
+export function planUpgrade({ templateFiles, manifest, projectFileStates, options }) {
+  const manifestFiles = manifest ? indexManifestFiles(manifest) : new Map();
+  const templatePaths = new Set([...templateFiles.keys()]);
+
+  const ops = [];
+
+  for (const [relPath, tf] of templateFiles.entries()) {
+    const state = projectFileStates.get(relPath) || { exists: false };
+    const mf = manifestFiles.get(relPath);
+    const decision = (mf && mf.decision) ? mf.decision : defaultDecision();
+
+    if (!state.exists) {
+      ops.push({
+        type: 'add',
+        path: relPath,
+        kind: tf.kind,
+        templateSha256: tf.templateSha256
+      });
+      continue;
+    }
+
+    if (options.force) {
+      ops.push({ type: 'overwrite', path: relPath, kind: tf.kind, templateSha256: tf.templateSha256, reason: 'force' });
+      continue;
+    }
+
+    if (mf && typeof mf.baseSha256 === 'string' && state.currentSha256 === mf.baseSha256) {
+      ops.push({ type: 'update', path: relPath, kind: tf.kind, templateSha256: tf.templateSha256, reason: 'unchanged' });
+      continue;
+    }
+
+    const conflictKind = mf ? 'conflict' : 'legacy-conflict';
+    let resolution = null;
+
+    if (options.overwriteChanged) resolution = 'overwrite';
+    else if (!options.isInteractive || options.yes) resolution = 'skip';
+    else if (decision && decision.remember) {
+      if (decision.onConflict === 'overwrite') resolution = 'overwrite';
+      if (decision.onConflict === 'skip') resolution = 'skip';
+    }
+
+    ops.push({
+      type: resolution === 'overwrite' ? 'overwrite' : resolution === 'skip' ? 'skip' : 'conflict',
+      path: relPath,
+      kind: tf.kind,
+      templateSha256: tf.templateSha256,
+      reason: conflictKind
+    });
+  }
+
+  const orphaned = [];
+  if (manifest) {
+    for (const f of manifest.files) {
+      if (!f || typeof f.path !== 'string') continue;
+      if (!templatePaths.has(f.path)) orphaned.push(f.path);
+    }
+  }
+
+  for (const p of orphaned) {
+    if (options.force || options.prune) ops.push({ type: 'remove', path: p, reason: 'orphaned' });
+    else ops.push({ type: 'orphaned', path: p, reason: 'orphaned' });
+  }
+
+  return ops;
+}

package/bin/lib/upgrade/sha256.js

@@ -0,0 +1,6 @@
+import crypto from 'crypto';
+
+export function sha256Hex(input) {
+  const buf = Buffer.isBuffer(input) ? input : Buffer.from(String(input));
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}

package/bin/lib/upgrade/template.js

@@ -0,0 +1,56 @@
+import path from 'path';
+import { sha256Hex } from './sha256.js';
+
+async function listFilesRecursive(fs, dirAbs, relBase = '') {
+  const entries = await fs.readdir(dirAbs, { withFileTypes: true });
+  const out = [];
+
+  for (const ent of entries) {
+    const rel = relBase ? `${relBase}/${ent.name}` : ent.name;
+    const abs = path.join(dirAbs, ent.name);
+
+    if (ent.isSymbolicLink()) {
+      throw new Error(`Template contains symlink (unsupported): ${rel}`);
+    }
+
+    if (ent.isDirectory()) {
+      out.push(...await listFilesRecursive(fs, abs, rel));
+      continue;
+    }
+
+    if (ent.isFile()) {
+      out.push({ rel, abs });
+    }
+  }
+
+  return out;
+}
+
+export async function readTemplateFiles({ fs, templateDirAbs, includeRootConfig, rootConfigPathAbs }) {
+  const files = new Map();
+
+  const templateEntries = await listFilesRecursive(fs, templateDirAbs);
+  for (const { rel, abs } of templateEntries) {
+    const content = await fs.readFile(abs);
+    const relPath = `.opencode/${rel.replace(/\\/g, '/')}`;
+    files.set(relPath, {
+      path: relPath,
+      kind: 'template',
+      content,
+      templateSha256: sha256Hex(content)
+    });
+  }
+
+  if (includeRootConfig) {
+    const content = await fs.readFile(rootConfigPathAbs);
+    const relPath = 'opencode.json';
+    files.set(relPath, {
+      path: relPath,
+      kind: 'root-config',
+      content,
+      templateSha256: sha256Hex(content)
+    });
+  }
+
+  return files;
+}

package/bin/lib/upgrade.js

@@ -0,0 +1,250 @@
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { promises as fs } from 'node:fs';
+
+function toPosix(p) {
+  return p.replaceAll('\\\\', '/');
+}
+
+function assertSafeRelativePath(rel) {
+  const normalized = toPosix(rel);
+  if (path.isAbsolute(normalized)) {
+    throw new Error(`Path must be relative: ${rel}`);
+  }
+  const parts = normalized.split('/');
+  if (parts.includes('..')) {
+    throw new Error(`Path traversal is not allowed: ${rel}`);
+  }
+}
+
+export function sha256Hex(content) {
+  const buf = Buffer.isBuffer(content) ? content : Buffer.from(String(content));
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+async function listFilesRecursive(rootDir) {
+  const out = [];
+
+  async function walk(currentDir) {
+    const entries = await fs.readdir(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isSymbolicLink()) continue;
+      const abs = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(abs);
+        continue;
+      }
+      out.push(abs);
+    }
+  }
+
+  await walk(rootDir);
+  return out;
+}
+
+export async function readManifest(manifestPath) {
+  try {
+    const raw = await fs.readFile(manifestPath, 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) return null;
+    throw err;
+  }
+}
+
+export async function writeManifest(manifestPath, manifest) {
+  await fs.mkdir(path.dirname(manifestPath), { recursive: true });
+  const json = JSON.stringify(manifest, null, 2) + '\n';
+  await fs.writeFile(manifestPath, json, 'utf8');
+}
+
+function manifestBaseShaByPath(manifest) {
+  const map = new Map();
+  if (!manifest) return map;
+
+  const files = manifest.files;
+  if (Array.isArray(files)) {
+    for (const f of files) {
+      if (!f || typeof f.path !== 'string') continue;
+      if (typeof f.baseSha256 === 'string' && f.baseSha256) {
+        map.set(toPosix(f.path), f.baseSha256);
+      }
+    }
+    return map;
+  }
+
+  if (files && typeof files === 'object') {
+    for (const [p, meta] of Object.entries(files)) {
+      if (meta && typeof meta.baseSha256 === 'string' && meta.baseSha256) {
+        map.set(toPosix(p), meta.baseSha256);
+      }
+    }
+  }
+
+  return map;
+}
+
+function upsertManifestFileEntry(filesArr, filePath, baseSha256, openkitVersion) {
+  const p = toPosix(filePath);
+  let existing = filesArr.find((f) => f && f.path === p);
+  if (!existing) {
+    existing = { path: p, kind: p.startsWith('.opencode/') ? 'template' : 'root-config' };
+    filesArr.push(existing);
+  }
+  existing.baseSha256 = baseSha256;
+  if (openkitVersion) existing.lastAppliedOpenkitVersion = openkitVersion;
+}
+
+export async function planUpgrade({
+  templateOpencodeDir,
+  projectDir,
+  manifestPath,
+  isTTY,
+  failOnChanges = false
+}) {
+  const manifest = await readManifest(manifestPath);
+  const baseShaByPath = manifestBaseShaByPath(manifest);
+  const hasManifest = Boolean(manifest);
+
+  const templateAbsFiles = await listFilesRecursive(templateOpencodeDir);
+  const operations = [];
+
+  const templateManagedPaths = new Set();
+  for (const absTemplatePath of templateAbsFiles) {
+    const relInOpencode = toPosix(path.relative(templateOpencodeDir, absTemplatePath));
+    assertSafeRelativePath(relInOpencode);
+    const managedPath = toPosix(path.posix.join('.opencode', relInOpencode));
+    templateManagedPaths.add(managedPath);
+
+    const destAbs = path.join(projectDir, managedPath);
+    const templateContent = await fs.readFile(absTemplatePath);
+    const templateSha = sha256Hex(templateContent);
+
+    try {
+      const currentContent = await fs.readFile(destAbs);
+      const currentSha = sha256Hex(currentContent);
+      if (!hasManifest) {
+        operations.push({
+          type: 'skip',
+          path: managedPath,
+          reason: isTTY ? 'legacy-existing-interactive' : 'legacy-existing-noninteractive',
+          templateSha,
+          currentSha
+        });
+        continue;
+      }
+
+      const baseSha = baseShaByPath.get(managedPath);
+      if (baseSha && currentSha === baseSha) {
+        operations.push({
+          type: 'update',
+          path: managedPath,
+          reason: 'matches-manifest-base',
+          templateSha,
+          currentSha,
+          baseSha
+        });
+      } else {
+        operations.push({
+          type: 'conflict',
+          path: managedPath,
+          reason: baseSha ? 'differs-from-manifest-base' : 'missing-manifest-entry',
+          templateSha,
+          currentSha,
+          baseSha: baseSha || null
+        });
+      }
+    } catch (err) {
+      if (!err || err.code !== 'ENOENT') throw err;
+      operations.push({
+        type: 'add',
+        path: managedPath,
+        reason: 'missing-on-disk',
+        templateSha
+      });
+    }
+  }
+
+  const orphaned = [];
+  if (hasManifest) {
+    for (const p of baseShaByPath.keys()) {
+      if (p.startsWith('.opencode/') && !templateManagedPaths.has(p)) {
+        orphaned.push(p);
+      }
+    }
+  }
+  for (const p of orphaned.sort()) {
+    operations.push({ type: 'orphaned', path: p, reason: 'missing-from-template' });
+  }
+
+  const summary = {
+    added: operations.filter((o) => o.type === 'add').map((o) => o.path),
+    updated: operations.filter((o) => o.type === 'update').map((o) => o.path),
+    skipped: operations.filter((o) => o.type === 'skip').map((o) => o.path),
+    conflicts: operations.filter((o) => o.type === 'conflict').map((o) => o.path),
+    orphaned: operations.filter((o) => o.type === 'orphaned').map((o) => o.path)
+  };
+
+  const exitCode = summary.conflicts.length > 0 && failOnChanges ? 2 : 0;
+
+  return {
+    mode: hasManifest ? 'manifest' : 'legacy',
+    operations,
+    summary,
+    exitCode
+  };
+}
+
+export async function applyUpgrade(plan, {
+  templateOpencodeDir,
+  projectDir,
+  manifestPath,
+  dryRun = false,
+  openkitVersion = null,
+  failOnChanges = false
+} = {}) {
+  const conflicts = plan?.summary?.conflicts?.length ? plan.summary.conflicts : [];
+  const exitCode = conflicts.length > 0 && failOnChanges ? 2 : 0;
+  if (dryRun) {
+    return { ...plan, exitCode, wrote: false };
+  }
+
+  const manifest = (await readManifest(manifestPath)) || {
+    schemaVersion: 1,
+    managedBy: '@paulojalowyj/openkit',
+    openkitVersion: openkitVersion || null,
+    projectRoot: '.',
+    managedPaths: ['.opencode'],
+    files: [],
+    history: []
+  };
+
+  if (!Array.isArray(manifest.files)) {
+    manifest.files = [];
+  }
+
+  for (const op of plan.operations) {
+    if (op.type !== 'add' && op.type !== 'update') continue;
+    const relInOpencode = op.path.replace(/^\.opencode\//, '');
+    assertSafeRelativePath(relInOpencode);
+
+    const srcAbs = path.join(templateOpencodeDir, relInOpencode);
+    const destAbs = path.join(projectDir, op.path);
+    await fs.mkdir(path.dirname(destAbs), { recursive: true });
+    const content = await fs.readFile(srcAbs);
+    await fs.writeFile(destAbs, content);
+    upsertManifestFileEntry(manifest.files, op.path, sha256Hex(content), openkitVersion);
+  }
+
+  manifest.openkitVersion = openkitVersion || manifest.openkitVersion;
+  manifest.history = Array.isArray(manifest.history) ? manifest.history : [];
+  manifest.history.push({
+    type: 'upgrade',
+    openkitVersion: openkitVersion || null,
+    timestamp: new Date().toISOString()
+  });
+
+  await writeManifest(manifestPath, manifest);
+
+  return { ...plan, exitCode, wrote: true };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@paulojalowyj/openkit",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "OpenKit - OpenCode Agent System - 15 specialized prompts, 33+ skills, validation scripts\n\nQuick Start:\n1. Install: npx @paulojalowyj/openkit init\n2. Start OpenCode: opencode\n3. Use workflows: /engineer, /plan, /impl, /test\n\nDocumentation: https://opencode.ai/docs",
   "main": "index.js",
   "bin": {
@@ -10,7 +10,7 @@
   "scripts": {
     "init": "node bin/cli.js init",
     "doctor": "node bin/cli.js doctor",
-    "test": "echo \"No tests yet - implement integration tests\"",
+    "test": "node --test test/*.test.js",
     "prepublishOnly": "node scripts/prepare.js",
     "version": "node scripts/update-version.js && git add -A"
   },