@ericrisco/rsc 0.1.22 → 0.1.24

package/README.md

@@ -150,6 +150,11 @@ rsc consult "I want to launch a SaaS"  # recommend only, no install
 rsc registry refresh                 # write .rsc/skill-registry.{json,md}
 rsc list                             # what rsc has installed
 rsc doctor                           # health check (state, hook, counts)
+rsc sync --target claude,codex       # refresh managed skills/hooks from the current package version
+rsc backups                          # list project-local snapshots
+rsc restore latest --dry-run         # preview restoring the newest snapshot
+rsc restore <snapshot-id>            # restore a project-local snapshot
+rsc upgrade --dry-run                # show npm upgrade + sync commands
 rsc uninstall postgresdb --dry-run   # preview a removal
 ```
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.22",
+  "version": "0.1.24",
   "counts": {
     "skills": 231
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/scripts/doctor.js

@@ -1,18 +1,27 @@
 import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { targetPaths } from '../targets/index.js';
 import { readState } from './lib/state.js';
 import { loadManifest } from './lib/manifest.js';
+import { listBackups } from './lib/backups.js';
 
 export function doctor({ target, home, cwd }) {
+  const root = cwd || process.cwd();
   const paths = targetPaths(target, home, cwd);
   const state = readState(paths.stateFile);
   const manifest = loadManifest();
+  const backups = listBackups({ cwd: root });
   const report = {
     target,
     installed: Object.keys(state.skills),
     missing: [],
     hookWired: existsSync(paths.hookTarget),
     manifestSkills: manifest.counts.skills,
+    backups: {
+      exists: existsSync(join(root, '.rsc', 'backups')),
+      count: backups.length,
+      latest: backups[0]?.id || null,
+    },
   };
   for (const [id, e] of Object.entries(state.skills)) {
     for (const f of e.files) if (!existsSync(f)) report.missing.push(`${id}:${f}`);

package/scripts/install-apply.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { planInstall } from './install-plan.js';
 import { targetPaths, writeSkill, wireHook, unwireHook, baseDir, TARGET_IDS } from '../targets/index.js';
 import { readState, writeState } from './lib/state.js';
+import { createBackup } from './lib/backups.js';
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const CLI_VERSION = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version;
@@ -32,10 +33,37 @@ function ensureBase(id, cwd, refresh) {
   return dest;
 }
 
-export async function applyInstall({ skillIds, target, home, cwd = process.cwd() }) {
+function generatedHookFiles({ target, cwd }) {
+  if (target !== 'claude') return [];
+  return [
+    join(cwd, '.rsc', 'session-start.mjs'),
+    join(cwd, '.rsc', 'worklog-checkpoint.mjs'),
+    join(cwd, '.rsc', 'ship-guard.mjs'),
+    join(cwd, '.rsc', 'danger-guard.mjs'),
+  ];
+}
+
+function managedPathsForInstall({ skillIds, target, home, cwd }) {
+  const paths = targetPaths(target, home, cwd);
+  const plan = planInstall({ skillIds, target, home, cwd });
+  const out = [paths.stateFile, versionFile(cwd)];
+  for (const step of plan) {
+    if (step.kind === 'skill') {
+      out.push(step.to, baseDir(step.id, cwd));
+    } else if (step.kind === 'hook') {
+      out.push(step.to, ...generatedHookFiles({ target, cwd }));
+    }
+  }
+  return [...new Set(out)];
+}
+
+export async function applyInstall({ skillIds, target, home, cwd = process.cwd(), operation = 'install', dryRun = false }) {
   const paths = targetPaths(target, home, cwd);
   const plan = planInstall({ skillIds, target, home, cwd });
+  const managedPaths = managedPathsForInstall({ skillIds, target, home, cwd });
+  if (dryRun) return { dryRun: true, skills: skillIds, paths: managedPaths };
   const state = readState(paths.stateFile);
+  const backup = createBackup({ cwd, operation, target, paths: managedPaths, cliVersion: CLI_VERSION });
   // Refresh bases when installing a different version than they were materialized at
   // (or a pre-versioning install where the marker is absent). Same version → no-op.
   const refresh = readBaseVersion(cwd) !== CLI_VERSION;
@@ -52,7 +80,7 @@ export async function applyInstall({ skillIds, target, home, cwd = process.cwd()
   writeState(paths.stateFile, state);
   mkdirSync(dirname(versionFile(cwd)), { recursive: true });
   writeFileSync(versionFile(cwd), CLI_VERSION + '\n');
-  return state;
+  return { ...state, backup };
 }
 
 export function listInstalled({ target, home, cwd = process.cwd() }) {
@@ -64,23 +92,52 @@ export async function uninstall({ skillIds, target, home, cwd = process.cwd(), d
   const paths = targetPaths(target, home, cwd);
   const state = readState(paths.stateFile);
   const removed = [];
+  const managedPaths = [paths.stateFile];
   for (const id of skillIds) {
     const entry = state.skills[id];
     if (!entry) continue;
     for (const f of entry.files) {
+      managedPaths.push(f);
       removed.push(f);
-      if (!dryRun && existsSync(f)) rmSync(f, { recursive: true, force: true });
     }
-    if (!dryRun) delete state.skills[id];
   }
-  if (!dryRun) writeState(paths.stateFile, state);
+  if (!removed.length) return removed;
+  if (dryRun) return removed;
+  createBackup({ cwd, operation: 'uninstall', target, paths: managedPaths, cliVersion: CLI_VERSION });
+  for (const id of skillIds) {
+    const entry = state.skills[id];
+    if (!entry) continue;
+    for (const f of entry.files) {
+      if (existsSync(f)) rmSync(f, { recursive: true, force: true });
+    }
+    delete state.skills[id];
+  }
+  writeState(paths.stateFile, state);
   return removed;
 }
 
+export async function syncInstalled({ target, home, cwd = process.cwd(), dryRun = false }) {
+  const paths = targetPaths(target, home, cwd);
+  const state = readState(paths.stateFile);
+  const ids = Object.keys(state.skills || {});
+  if (!ids.length) return dryRun ? { dryRun: true, synced: [], paths: [] } : { synced: [], backup: null };
+  if (dryRun) {
+    return {
+      dryRun: true,
+      synced: ids,
+      paths: managedPathsForInstall({ skillIds: ids, target, home, cwd }),
+    };
+  }
+  const nextState = await applyInstall({ skillIds: ids, target, home, cwd, operation: 'sync' });
+  return { synced: ids, backup: nextState.backup };
+}
+
 // Remove EVERYTHING rsc put in this project: installed skills across all targets,
 // the wired hooks (settings.json entries / AGENTS-blocks / cursor rules), and the
 // shared `.rsc/` (base + hook scripts + version marker). `02-DOCS/` is the user's
 // own knowledge — kept unless `withDocs` is set. Returns the paths touched.
+// Note: backups live under `.rsc/backups/`, which this removes — so purge does not
+// snapshot (a pre-purge backup would delete itself). It is the deliberate escape hatch.
 export async function purge({ home, cwd = process.cwd(), withDocs = false, dryRun = false } = {}) {
   const removed = [];
   const drop = (p, recursive = false) => {

package/scripts/lib/backups.js

@@ -0,0 +1,154 @@
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
+
+const SCHEMA_VERSION = 1;
+
+export function backupsDir(cwd = process.cwd()) {
+  return join(cwd, '.rsc', 'backups');
+}
+
+export function createBackup({ cwd = process.cwd(), operation, target, paths, cliVersion, now = new Date() }) {
+  const uniquePaths = [...new Set((paths || []).filter(Boolean))];
+  const id = uniqueSnapshotId({ cwd, now, operation, target });
+  const root = join(backupsDir(cwd), id);
+  const filesRoot = join(root, 'files');
+  mkdirSync(filesRoot, { recursive: true });
+
+  const entries = uniquePaths.map((absPath) => snapshotEntry({ cwd, root, absPath }));
+  const manifest = {
+    schemaVersion: SCHEMA_VERSION,
+    id,
+    createdAt: now.toISOString(),
+    operation,
+    target,
+    cwd,
+    cliVersion,
+    entries,
+  };
+  writeFileSync(join(root, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+  return manifest;
+}
+
+export function listBackups({ cwd = process.cwd() } = {}) {
+  const dir = backupsDir(cwd);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .map((id) => readManifest({ cwd, id }))
+    .filter(Boolean)
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.id.localeCompare(a.id));
+}
+
+export function restoreBackup({ cwd = process.cwd(), id, dryRun = false }) {
+  const snapshot = resolveSnapshot({ cwd, id });
+  const changed = [];
+  for (const entry of snapshot.entries) {
+    const absPath = safeJoin(cwd, entry.path);
+    changed.push(absPath);
+    if (dryRun) continue;
+    restoreEntry({ cwd, snapshot, entry, absPath });
+  }
+  return { snapshot, changed };
+}
+
+function snapshotEntry({ cwd, root, absPath }) {
+  const rel = safeRelative(cwd, absPath);
+  if (!existsSync(absPath)) return { path: rel, existed: false, kind: 'missing' };
+
+  const stat = lstatSync(absPath);
+  if (stat.isSymbolicLink()) {
+    return { path: rel, existed: true, kind: 'symlink', linkTarget: readlinkSync(absPath) };
+  }
+
+  const contentPath = join('files', rel);
+  const contentAbs = join(root, contentPath);
+  mkdirSync(dirname(contentAbs), { recursive: true });
+  if (stat.isDirectory()) {
+    cpSync(absPath, contentAbs, { recursive: true });
+    return { path: rel, existed: true, kind: 'dir', contentPath };
+  }
+
+  cpSync(absPath, contentAbs);
+  return { path: rel, existed: true, kind: 'file', contentPath };
+}
+
+function restoreEntry({ cwd, snapshot, entry, absPath }) {
+  if (!entry.existed) {
+    rmSync(absPath, { recursive: true, force: true });
+    return;
+  }
+
+  rmSync(absPath, { recursive: true, force: true });
+  mkdirSync(dirname(absPath), { recursive: true });
+  if (entry.kind === 'symlink') {
+    symlinkSync(entry.linkTarget, absPath, process.platform === 'win32' ? 'junction' : undefined);
+    return;
+  }
+
+  const contentAbs = join(backupsDir(cwd), snapshot.id, entry.contentPath);
+  cpSync(contentAbs, absPath, { recursive: entry.kind === 'dir' });
+}
+
+function resolveSnapshot({ cwd, id }) {
+  if (!id) throw new Error('restore requires a snapshot id or latest');
+  if (id === 'latest') {
+    const latest = listBackups({ cwd })[0];
+    if (!latest) throw new Error('no backups found');
+    return latest;
+  }
+
+  const manifest = readManifest({ cwd, id });
+  if (!manifest) throw new Error(`backup not found: ${id}`);
+  return manifest;
+}
+
+function readManifest({ cwd, id }) {
+  const path = join(backupsDir(cwd), id, 'manifest.json');
+  if (!existsSync(path)) return undefined;
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function uniqueSnapshotId({ cwd, now, operation, target }) {
+  const base = snapshotId({ now, operation, target });
+  let id = base;
+  let counter = 2;
+  while (existsSync(join(backupsDir(cwd), id))) {
+    id = `${base}-${counter}`;
+    counter += 1;
+  }
+  return id;
+}
+
+function snapshotId({ now, operation, target }) {
+  const stamp = now.toISOString().replace(/[-:]/g, '').replace(/\..*/, '').replace('T', '-');
+  return `${stamp}-${safeId(operation)}-${safeId(target || 'all')}`;
+}
+
+function safeId(value) {
+  return String(value).replace(/[^a-z0-9._-]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase();
+}
+
+function safeRelative(cwd, absPath) {
+  const rel = relative(cwd, absPath);
+  if (!rel || rel.startsWith('..') || rel.split(sep).includes('..')) {
+    throw new Error(`path is outside project root: ${absPath}`);
+  }
+  return rel.split(sep).join('/');
+}
+
+function safeJoin(cwd, relPath) {
+  if (!relPath || isAbsolute(relPath) || relPath.split('/').includes('..')) {
+    throw new Error(`path is outside project root: ${relPath}`);
+  }
+  return join(cwd, ...relPath.split('/'));
+}

package/scripts/lib/upgrade.js

@@ -0,0 +1,18 @@
+import { spawnSync } from 'node:child_process';
+
+export function upgradePlan({ targets = [] } = {}) {
+  const targetArg = targets.length ? targets.join(',') : '<target>';
+  return {
+    installCommand: 'npm install -g @ericrisco/rsc@latest',
+    syncCommand: `rsc sync --target ${targetArg}`,
+  };
+}
+
+export function runUpgrade({ targets = [], dryRun = false, global = false } = {}) {
+  const plan = upgradePlan({ targets });
+  if (dryRun || !global) return { ran: false, plan };
+
+  const result = spawnSync('npm', ['install', '-g', '@ericrisco/rsc@latest'], { stdio: 'inherit' });
+  if (result.status !== 0) throw new Error('npm global upgrade failed');
+  return { ran: true, plan };
+}

package/scripts/rsc.js

@@ -4,12 +4,14 @@ import { detectTarget, TARGETS } from '../targets/index.js';
 import { detectRepo } from './detect-repo.js';
 import { rank } from './consult.js';
 import { expandRecommends, toOutcomes, hasOutcome } from './lib/recommend.js';
-import { applyInstall, listInstalled, uninstall, purge } from './install-apply.js';
+import { applyInstall, listInstalled, uninstall, syncInstalled, purge } from './install-apply.js';
 import { doctor } from './doctor.js';
 import { say, select, pickFrom, banner, confirm } from './lib/ui.js';
 import { refreshRegistry, registryStatus } from './lib/registry.js';
 import { audit, writeAuditReport } from './audit.js';
 import { DOMAINS } from './lib/domains.js';
+import { listBackups, restoreBackup } from './lib/backups.js';
+import { runUpgrade } from './lib/upgrade.js';
 
 const argv = process.argv.slice(2);
 const cmd = argv[0];
@@ -200,6 +202,43 @@ async function main() {
       return void say(listInstalled({ target }).join('\n') || '(nothing installed)');
     case 'doctor':
       return void say(JSON.stringify(doctor({ target }), null, 2));
+    case 'sync': {
+      const dry = argv.includes('--dry-run');
+      for (const t of targets) {
+        const result = await syncInstalled({ target: t, dryRun: dry });
+        const verb = dry ? 'Would sync' : 'Synced';
+        say(`${verb} ${t}: ${result.synced.length ? result.synced.join(', ') : '(nothing to sync)'}`);
+        if (dry && result.paths?.length) {
+          for (const p of result.paths) say(`  ${p}`);
+        }
+      }
+      return;
+    }
+    case 'backups': {
+      const backups = listBackups();
+      if (!backups.length) return void say('(no backups)');
+      for (const b of backups) {
+        say(`${b.id}\t${b.operation}\t${b.target}\t${b.entries.length} files\t${b.createdAt}`);
+      }
+      return;
+    }
+    case 'restore': {
+      const dry = argv.includes('--dry-run');
+      const id = argv.slice(1).find((a) => !a.startsWith('--'));
+      const result = restoreBackup({ id, dryRun: dry });
+      say(`${dry ? 'Would restore' : 'Restored'} ${result.snapshot.id}`);
+      for (const p of result.changed) say(`  ${p}`);
+      return;
+    }
+    case 'upgrade': {
+      const dry = argv.includes('--dry-run');
+      const global = argv.includes('--global');
+      const result = runUpgrade({ targets, dryRun: dry, global });
+      if (result.ran) say('Upgraded global @ericrisco/rsc. Restart your shell if needed.');
+      else say(`${dry ? 'Would run' : 'Upgrade guide'}: ${result.plan.installCommand}`);
+      say(`After upgrade: ${result.plan.syncCommand}`);
+      return;
+    }
     case 'registry': {
       const sub = argv[1];
       if (sub === 'refresh') {
@@ -226,7 +265,7 @@ async function main() {
       return void (await runPurge(argv.includes('--dry-run'), argv.includes('--with-docs')));
     default:
       say(`rsc: unknown command '${cmd}'.`);
-      say('Use: npx @ericrisco/rsc | add <id...> | install --profile <p> | consult "<text>" | list | audit | registry refresh | doctor | uninstall <id> | purge');
+      say('Use: npx @ericrisco/rsc | add <id...> | install --profile <p> | consult "<text>" | list | audit | registry refresh | doctor | sync | backups | restore <id|latest> | upgrade | uninstall <id> | purge');
   }
 }