@ghostlygawd/codeweb 0.9.0

package/scripts/refresh.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// codeweb refresh (F0) — re-extract a graph's nodes+edges from current disk so an agent's mid-task
+// queries (impact / context-pack / callers) reflect the working tree, not a stale snapshot. Uses the
+// extractor's per-file scan cache (only changed files are re-scanned), re-attaches each surviving
+// node's domain by id, and drops overlaps (they need the full pipeline; not needed by the query
+// tools). meta is preserved. Read-only over the target source; never executes it.
+//
+// Usage: node refresh.mjs <graph.json> [--cache <path>] [--json]
+// Exit: 0 ok, 2 usage / missing meta.root.
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const USAGE = 'usage: refresh.mjs <graph.json> [--cache <path>] [--json]';
+import { die, emitJson, finish } from './lib/cli.mjs';
+
+const argv = process.argv.slice(2);
+let json = false, cache = null; const pos = [];
+for (let i = 0; i < argv.length; i++) {
+  const t = argv[i];
+  if (t === '--json') json = true;
+  else if (t === '--cache') cache = argv[++i];
+  else if (!t.startsWith('-')) pos.push(t);
+}
+const graphPath = pos[0];
+if (!graphPath) die(USAGE, 2);
+
+const abs = resolve(graphPath);
+if (!existsSync(abs)) die(`graph not found: ${abs}`, 2);
+let graph;
+try { graph = JSON.parse(readFileSync(abs, 'utf8')); }
+catch (e) { die(`invalid JSON in ${abs}: ${e.message}`, 2); }
+
+const root = graph.meta && graph.meta.root;
+if (!root || !existsSync(root)) die(`cannot refresh: graph.meta.root is missing or not on disk (got ${root || 'none'}) — refresh re-extracts from the recorded target root`, 2);
+
+// re-extract (cached) from the recorded root; the extractor emits the fragment on stdout
+const cachePath = cache || join(dirname(abs), 'extract-cache.json'); // default cache beside the graph
+const r = spawnSync(process.execPath, [join(HERE, 'extract-symbols.mjs'), root, '--cache', cachePath], { encoding: 'utf8', maxBuffer: 1 << 28 });
+if (r.status !== 0) die(`extract failed: ${(r.stderr || '').trim() || r.status}`, 2);
+let fresh;
+try { fresh = JSON.parse(r.stdout); }
+catch (e) { die(`extractor produced invalid JSON: ${e.message}`, 2); }
+
+// re-attach each surviving node's domain by id (domains[] summaries kept; node domains carried over)
+const oldDomainById = new Map(graph.nodes.filter((n) => n.domain && n.domain !== 'unassigned').map((n) => [n.id, n.domain]));
+let reattached = 0;
+for (const n of fresh.nodes) { const d = oldDomainById.get(n.id); if (d) { n.domain = d; reattached++; } else if (n.domain == null) n.domain = ''; }
+
+const before = { nodes: graph.nodes.length, edges: graph.edges.length };
+const updated = {
+  meta: { ...graph.meta, ...fresh.meta, target: graph.meta.target || fresh.meta.target },
+  nodes: fresh.nodes,
+  edges: fresh.edges,
+  domains: graph.domains || [],   // domain summaries preserved (node assignments re-attached above)
+  overlaps: [],                   // stale after an edit — recompute via the full pipeline when needed
+};
+writeFileSync(abs, JSON.stringify(updated));
+
+const payload = {
+  graph: abs, root,
+  before, after: { nodes: updated.nodes.length, edges: updated.edges.length },
+  domainsReattached: reattached, scanned: /scanned (\d+)/.exec(r.stderr)?.[1] ?? null,
+};
+if (json) { emitJson(payload); } else {
+console.log(`codeweb refresh: ${root}`);
+console.log(`  nodes ${before.nodes} -> ${updated.nodes.length}   edges ${before.edges} -> ${updated.edges.length}   domains re-attached ${reattached}`);
+console.log(`  overlaps dropped (run the full pipeline to recompute). scanned ${payload.scanned ?? '?'} file(s).`);
+finish();
+}

package/scripts/release-utils.mjs

@@ -0,0 +1,158 @@
+/**
+ * Shared, dependency-free helpers for the codeweb release ecosystem.
+ *
+ * The single source of truth for the version is package.json; the single source
+ * of truth for the MCP tool count is the TOOLS table in scripts/mcp-server.mjs.
+ * Everything else is derived from or checked against those two facts.
+ *
+ * Pure functions are exported for unit testing (bumpVersion, rollChangelog,
+ * syncTargets); the file-touching helpers are thin wrappers over them.
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const readText = (p) => readFileSync(p, 'utf8');
+export const writeText = (p, s) => writeFileSync(p, s);
+
+/** Canonical version (from package.json). */
+export function getVersion(root) {
+  return JSON.parse(readText(join(root, 'package.json'))).version;
+}
+
+/** Count the MCP tools at the source: the TOOLS table in scripts/mcp-server.mjs. */
+export function mcpToolCount(root) {
+  const src = readText(join(root, 'scripts', 'mcp-server.mjs'));
+  return (src.match(/name:\s*'codeweb_[a-z_]+'/g) || []).length;
+}
+
+/** Count the tools the website advertises (sum of toolPhases in product.json). */
+export function productToolCount(root) {
+  const p = JSON.parse(readText(join(root, 'site', 'data', 'product.json')));
+  return p.toolPhases.reduce((n, ph) => n + ph.tools.length, 0);
+}
+
+/**
+ * Where the version + tool-count must be mirrored away from package.json.
+ * Each sub is [regExp, replacementString]; ${version}/${count} are interpolated,
+ * $1/$2 are honored backrefs so surrounding formatting is preserved.
+ */
+export function syncTargets(version, count) {
+  return [
+    {
+      file: '.claude-plugin/plugin.json',
+      subs: [
+        [/("version":\s*")[^"]+(")/, `$1${version}$2`],
+        [/(\d+)(\s+deterministic read-only query tools)/, `${count}$2`],
+      ],
+    },
+    {
+      file: 'skills/codebase-anatomy/SKILL.md',
+      subs: [[/(^version:\s*).+$/m, `$1${version}`]],
+    },
+    {
+      file: 'README.md',
+      subs: [[/(badge\/version-)\d+\.\d+\.\d+(-)/, `$1${version}$2`]],
+    },
+    {
+      // no-op for the shipped server (version derives from package.json, no literal); repairs a
+      // hardcoded serverInfo literal if one is ever reintroduced.
+      file: 'scripts/mcp-server.mjs',
+      subs: [[/(version:\s*')\d+\.\d+\.\d+(')/, `$1${version}$2`]],
+    },
+  ];
+}
+
+/** Apply syncTargets to disk. Returns the list of files that changed. */
+export function applySync(root, version, count) {
+  const changed = [];
+  for (const t of syncTargets(version, count)) {
+    const p = join(root, t.file);
+    if (!existsSync(p)) continue;
+    const before = readText(p);
+    let after = before;
+    for (const [re, rep] of t.subs) after = after.replace(re, rep);
+    if (after !== before) { writeText(p, after); changed.push(t.file); }
+  }
+  return changed;
+}
+
+/** Read-only consistency audit across the public-comms surface. */
+export function checkConsistency(root) {
+  const version = getVersion(root);
+  const count = mcpToolCount(root);
+  const problems = [];
+
+  const plugin = JSON.parse(readText(join(root, '.claude-plugin', 'plugin.json')));
+  if (plugin.version !== version) problems.push(`plugin.json version ${plugin.version} != package.json ${version}`);
+  const advertised = (plugin.description.match(/(\d+)\s+deterministic read-only query tools/) || [])[1];
+  if (advertised && Number(advertised) !== count) problems.push(`plugin.json advertises ${advertised} tools; MCP server exposes ${count}`);
+
+  const skill = readText(join(root, 'skills', 'codebase-anatomy', 'SKILL.md'));
+  const skillVer = (skill.match(/^version:\s*(.+)$/m) || [])[1];
+  if (skillVer && skillVer.trim() !== version) problems.push(`SKILL.md version ${skillVer.trim()} != ${version}`);
+
+  const pc = productToolCount(root);
+  if (pc !== count) problems.push(`product.json lists ${pc} tools; MCP server exposes ${count}`);
+
+  const readmePath = join(root, 'README.md');
+  if (existsSync(readmePath)) {
+    const rb = (readText(readmePath).match(/badge\/version-(\d+\.\d+\.\d+)-/) || [])[1];
+    if (rb && rb !== version) problems.push(`README version badge ${rb} != ${version}`);
+  }
+
+  const clPath = join(root, 'CHANGELOG.md');
+  if (existsSync(clPath)) {
+    const cl = readText(clPath);
+    const verRe = new RegExp(`^##\\s*\\[${version.replace(/\./g, '\\.')}\\]`, 'm');
+    if (!verRe.test(cl)) problems.push(`CHANGELOG.md has no section for v${version}`);
+  } else {
+    problems.push('CHANGELOG.md is missing');
+  }
+
+  // The MCP handshake surface: serverInfo.version must agree with package.json. The shipped server
+  // derives it dynamically (no literal — nothing to drift); a hardcoded literal is tolerated only
+  // while it matches, and version-sync repairs it. (A literal '0.1.0' drifted for a whole release
+  // because nothing audited this file.)
+  const mcpPath = join(root, 'scripts', 'mcp-server.mjs');
+  if (existsSync(mcpPath)) {
+    const hard = readText(mcpPath).match(/version:\s*'(\d+\.\d+\.\d+)'/);
+    if (hard && hard[1] !== version) problems.push(`mcp-server.mjs hardcodes serverInfo version ${hard[1]} != package.json ${version}`);
+  }
+
+  return { ok: problems.length === 0, version, count, problems };
+}
+
+/** Semantic-version bump. */
+export function bumpVersion(v, level) {
+  const [a, b, c] = v.split('.').map(Number);
+  if (level === 'major') return `${a + 1}.0.0`;
+  if (level === 'minor') return `${a}.${b + 1}.0`;
+  if (level === 'patch') return `${a}.${b}.${c + 1}`;
+  throw new Error(`bumpVersion: unknown level "${level}"`);
+}
+
+/**
+ * Roll a Keep-a-Changelog document for a release: the body currently under
+ * [Unreleased] becomes the new dated [version] section, and [Unreleased] is reset.
+ * Link-reference definitions for [Unreleased] and [version] are refreshed.
+ */
+export function rollChangelog(md, version, date, repo = 'https://github.com/GhostlyGawd/codeweb') {
+  const PLACEHOLDER = '_Nothing yet. Open work lands here before it ships in the next tagged release._';
+  const unrelRe = /## \[Unreleased\]\s*([\s\S]*?)(?=\n## \[|\n\[Unreleased\]:|$)/;
+  const m = md.match(unrelRe);
+  if (!m) throw new Error('rollChangelog: no [Unreleased] section found');
+  const body = m[1].replace(/^\s+|\s+$/g, '');
+  if (!body || body === PLACEHOLDER) throw new Error('rollChangelog: [Unreleased] is empty — nothing to release');
+
+  const prev = (md.match(/## \[(\d+\.\d+\.\d+)\]/) || [])[1];
+  const replacement = `## [Unreleased]\n\n${PLACEHOLDER}\n\n## [${version}] - ${date}\n\n${body}\n`;
+  let out = md.replace(unrelRe, replacement);
+
+  // refresh link refs
+  out = out.replace(/^\[Unreleased\]:.*$/m, `[Unreleased]: ${repo}/compare/v${version}...HEAD`);
+  const verLink = `[${version}]: ${repo}/compare/${prev ? `v${prev}` : 'main'}...v${version}`;
+  if (!new RegExp(`^\\[${version.replace(/\./g, '\\.')}\\]:`, 'm').test(out)) {
+    out = out.replace(/^(\[Unreleased\]:.*\n)/m, `$1${verLink}\n`);
+  }
+  return out;
+}

package/scripts/release.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * codeweb release prep — updates the whole file ecosystem in one motion, then
+ * stops and hands the gated git steps (commit, tag, push, GitHub release) to you.
+ *
+ *   node scripts/release.mjs --minor            # 0.2.0 -> 0.3.0
+ *   node scripts/release.mjs --version=1.0.0
+ *   node scripts/release.mjs --minor --dry-run  # show the plan, change nothing
+ *
+ * What it does (non-dry): bump package.json -> roll CHANGELOG [Unreleased] into a
+ * dated version section -> version-sync plugin.json + SKILL.md -> rebuild the site
+ * -> re-check consistency. It never runs git; it prints the exact commands to finish.
+ */
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { getVersion, mcpToolCount, applySync, bumpVersion, rollChangelog, checkConsistency, readText, writeText } from './release-utils.mjs';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const args = process.argv.slice(2);
+const dry = args.includes('--dry-run');
+const bumpLevel = (args.find((a) => ['--major', '--minor', '--patch'].includes(a)) || '').slice(2);
+const explicit = (args.find((a) => a.startsWith('--version=')) || '').split('=')[1];
+const today = new Date().toISOString().slice(0, 10);
+
+const current = getVersion(ROOT);
+const next = explicit || (bumpLevel ? bumpVersion(current, bumpLevel) : null);
+if (!next) {
+  process.stderr.write('usage: release.mjs (--major|--minor|--patch | --version=X.Y.Z) [--dry-run]\n');
+  process.exit(2);
+}
+const count = mcpToolCount(ROOT);
+
+console.log(`codeweb release: ${current} -> ${next}  (${count} MCP tools)${dry ? '  [dry-run]' : ''}`);
+['bump package.json',
+ `roll CHANGELOG.md: [Unreleased] -> [${next}] - ${today}`,
+ 'version-sync plugin.json + SKILL.md',
+ 'rebuild site (node site/build.mjs)'].forEach((s, i) => console.log(`  ${i + 1}. ${s}`));
+
+if (dry) {
+  try {
+    const preview = rollChangelog(readText(join(ROOT, 'CHANGELOG.md')), next, today).split('\n').slice(0, 16).join('\n');
+    console.log('\n--- CHANGELOG preview ---\n' + preview);
+  } catch (e) { console.log(`  (changelog: ${e.message})`); }
+  console.log('\nDry run — no files changed.');
+  process.exit(0);
+}
+
+const pkgPath = join(ROOT, 'package.json');
+writeText(pkgPath, readText(pkgPath).replace(/("version":\s*")[^"]+(")/, `$1${next}$2`));
+writeText(join(ROOT, 'CHANGELOG.md'), rollChangelog(readText(join(ROOT, 'CHANGELOG.md')), next, today));
+const changed = applySync(ROOT, next, count);
+execFileSync(process.execPath, [join(ROOT, 'site', 'build.mjs')], { stdio: 'inherit' });
+
+const audit = checkConsistency(ROOT);
+console.log(`\nupdated: package.json, CHANGELOG.md, ${changed.join(', ')}, docs/`);
+console.log(audit.ok ? 'consistency: OK' : `consistency: ${audit.problems.length} problem(s) — ${audit.problems.join('; ')}`);
+console.log('\nNext (gated — run when ready):');
+console.log(`  git add -A && git commit -m "release: v${next}"`);
+console.log(`  git tag -a v${next} -m "codeweb v${next}"`);
+console.log('  git push origin main --tags');
+console.log(`  gh release create v${next} --title "codeweb v${next}" --notes-from-tag`);