verity-framework 0.1.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "verity-framework",
+  "version": "0.1.0",
+  "description": "Verity — a CI/CD-native, GitHub-native, production-lifecycle AI software delivery framework.",
+  "keywords": ["verity", "ai", "ci-cd", "github", "devops", "agent", "framework"],
+  "author": "Sean Mahoney",
+  "license": "MIT",
+  "homepage": "https://github.com/seanerama/verity-framework#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seanerama/verity-framework.git"
+  },
+  "bugs": {
+    "url": "https://github.com/seanerama/verity-framework/issues"
+  },
+  "bin": {
+    "verity": "verity/bin/verity.cjs"
+  },
+  "files": ["verity", "commands", "README.md", "LICENSE"],
+  "engines": {
+    "node": ">=16.7.0"
+  },
+  "scripts": {
+    "test": "node scripts/run-tests.cjs",
+    "lint": "biome ci .",
+    "prepublishOnly": "npm run lint && npm test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "1.9.4"
+  }
+}

package/verity/bin/lib/adr.cjs

@@ -0,0 +1,67 @@
+// Architecture Decision Records — docs/adr/NNNN-slug.md (framework-spec.md §4.3).
+// Every architectural decision/deviation is an append-only, numbered ADR.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { generateSlug, render } = require('./core.cjs');
+
+const TEMPLATE = path.join(__dirname, '..', '..', 'templates', 'adr.md.tmpl');
+
+function adrDir(cwd) {
+  return path.join(cwd, 'docs', 'adr');
+}
+
+function nextNumber(cwd) {
+  const dir = adrDir(cwd);
+  if (!fs.existsSync(dir)) {
+    return 1;
+  }
+  const nums = fs
+    .readdirSync(dir)
+    .map((name) => Number.parseInt(name.slice(0, 4), 10))
+    .filter((n) => Number.isFinite(n));
+  return nums.length > 0 ? Math.max(...nums) + 1 : 1;
+}
+
+function create(cwd, title, opts = {}) {
+  if (!title) {
+    throw new Error('adr new requires a title');
+  }
+  const padded = String(nextNumber(cwd)).padStart(4, '0');
+  const slug = generateSlug(title) || 'decision';
+  const file = path.join(adrDir(cwd), `${padded}-${slug}.md`);
+  fs.mkdirSync(adrDir(cwd), { recursive: true });
+  const content = render(fs.readFileSync(TEMPLATE, 'utf8'), {
+    number: padded,
+    title,
+    status: opts.status || 'Proposed',
+    date: new Date().toISOString().slice(0, 10),
+  });
+  fs.writeFileSync(file, content);
+  return { number: padded, title, path: file };
+}
+
+function list(cwd) {
+  const dir = adrDir(cwd);
+  const adrs = fs.existsSync(dir)
+    ? fs
+        .readdirSync(dir)
+        .filter((n) => n.endsWith('.md'))
+        .sort()
+    : [];
+  return { adrs };
+}
+
+function dispatch(args, flags) {
+  const cwd = flags.cwd || process.cwd();
+  const verb = args[0];
+  if (verb === 'new') {
+    return create(cwd, args[1], { status: flags.status });
+  }
+  if (verb === 'list') {
+    return list(cwd);
+  }
+  throw new Error(`unknown adr verb: ${verb || '(none)'} — use new|list`);
+}
+
+module.exports = { adrDir, nextNumber, create, list, dispatch };

package/verity/bin/lib/catalog.cjs

@@ -0,0 +1,81 @@
+// Design guides + drop-in feature catalog (framework-spec.md §4.5).
+// Guides are RECOMMENDATIONS the Architect reviews; features are pre-packaged
+// stage-sets the Architect can offer. Both ship as sample content under
+// design-guides/ and are read-only discovery here (org override is future config).
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Ships inside the package internals (verity/design-guides) so it travels with
+// `verity install` and npm publish.
+const GUIDES_DIR = path.join(__dirname, '..', '..', 'design-guides');
+const FEATURES_DIR = path.join(GUIDES_DIR, 'features');
+
+function parseFrontmatter(text) {
+  const meta = {};
+  const match = text.match(/^---\n([\s\S]*?)\n---/);
+  if (match) {
+    for (const line of match[1].split('\n')) {
+      const idx = line.indexOf(':');
+      if (idx > 0) {
+        meta[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+      }
+    }
+  }
+  return meta;
+}
+
+function listDir(dir) {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+  return fs
+    .readdirSync(dir)
+    .filter((name) => name.endsWith('.md'))
+    .sort()
+    .map((name) => {
+      const meta = parseFrontmatter(fs.readFileSync(path.join(dir, name), 'utf8'));
+      return { id: name.replace(/\.md$/, ''), title: meta.title || name, ...meta };
+    });
+}
+
+function showFile(dir, id) {
+  if (!id) {
+    throw new Error('show requires an id');
+  }
+  const file = path.join(dir, `${id}.md`);
+  if (!fs.existsSync(file)) {
+    throw new Error(`not found: ${id}`);
+  }
+  return { id, content: fs.readFileSync(file, 'utf8') };
+}
+
+function guidesDispatch(args) {
+  const verb = args[0];
+  if (verb === 'list') {
+    return { guides: listDir(GUIDES_DIR) };
+  }
+  if (verb === 'show') {
+    return showFile(GUIDES_DIR, args[1]);
+  }
+  throw new Error(`unknown guides verb: ${verb || '(none)'} — use list|show`);
+}
+
+function featureDispatch(args) {
+  const verb = args[0];
+  if (verb === 'list') {
+    return { features: listDir(FEATURES_DIR) };
+  }
+  if (verb === 'show') {
+    return showFile(FEATURES_DIR, args[1]);
+  }
+  throw new Error(`unknown feature verb: ${verb || '(none)'} — use list|show`);
+}
+
+module.exports = {
+  GUIDES_DIR,
+  FEATURES_DIR,
+  parseFrontmatter,
+  listDir,
+  guidesDispatch,
+  featureDispatch,
+};

package/verity/bin/lib/config.cjs

@@ -0,0 +1,119 @@
+// Verity project config — `.verity/config.json`. Carried pattern from 1.4.
+// AUTHOR/DERIVE: writes/reads the project's config knobs (NOT integration state).
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULTS = {
+  version: '1.0',
+  model_profile: 'balanced',
+  // Release/Deploy Operator gate: confirm (human) by default, or auto. (spec §6)
+  prod_promote: 'confirm',
+};
+
+function configPath(cwd) {
+  return path.join(cwd, '.verity', 'config.json');
+}
+
+function readConfig(cwd) {
+  const p = configPath(cwd);
+  if (!fs.existsSync(p)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function ensure(cwd) {
+  const p = configPath(cwd);
+  if (fs.existsSync(p)) {
+    return { created: false, path: p, config: readConfig(cwd) };
+  }
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const cfg = { ...DEFAULTS };
+  fs.writeFileSync(p, `${JSON.stringify(cfg, null, 2)}\n`);
+  return { created: true, path: p, config: cfg };
+}
+
+function getAt(obj, dotted) {
+  let node = obj;
+  for (const key of dotted.split('.')) {
+    if (node === null || node === undefined) {
+      return undefined;
+    }
+    node = node[key];
+  }
+  return node;
+}
+
+function setAt(obj, dotted, value) {
+  const keys = dotted.split('.');
+  let node = obj;
+  for (let i = 0; i < keys.length - 1; i += 1) {
+    if (node[keys[i]] === null || typeof node[keys[i]] !== 'object') {
+      node[keys[i]] = {};
+    }
+    node = node[keys[i]];
+  }
+  node[keys[keys.length - 1]] = value;
+}
+
+function coerce(value) {
+  if (value === 'true') {
+    return true;
+  }
+  if (value === 'false') {
+    return false;
+  }
+  if (/^-?\d+$/.test(value)) {
+    return Number(value);
+  }
+  return value;
+}
+
+function get(cwd, key) {
+  const cfg = readConfig(cwd) || { ...DEFAULTS };
+  if (!key) {
+    return { config: cfg };
+  }
+  const value = getAt(cfg, key);
+  return {
+    key,
+    value,
+    raw: value === null || value === undefined ? '' : String(value),
+  };
+}
+
+function set(cwd, key, rawValue) {
+  const { config: cfg } = ensure(cwd);
+  const value = coerce(rawValue);
+  setAt(cfg, key, value);
+  fs.writeFileSync(configPath(cwd), `${JSON.stringify(cfg, null, 2)}\n`);
+  return { key, value, path: configPath(cwd) };
+}
+
+function dispatch(args, flags) {
+  const verb = args[0];
+  const cwd = flags.cwd || process.cwd();
+  if (verb === 'ensure') {
+    return ensure(cwd);
+  }
+  if (verb === 'get') {
+    return get(cwd, args[1]);
+  }
+  if (verb === 'set') {
+    return set(cwd, args[1], args[2]);
+  }
+  throw new Error(`unknown config verb: ${verb || '(none)'} — use ensure|get|set`);
+}
+
+module.exports = {
+  DEFAULTS,
+  configPath,
+  readConfig,
+  ensure,
+  get,
+  set,
+  dispatch,
+  getAt,
+  setAt,
+  coerce,
+};

package/verity/bin/lib/contract.cjs

@@ -0,0 +1,57 @@
+// Interface contracts — contracts/<name>.md (framework-spec.md §4.3).
+// Contracts are MANDATES, frozen early. A change is ADDITIVE only; a breaking
+// change is a NEW contract, not an edit — so `new` refuses to overwrite.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { validateSlug, render } = require('./core.cjs');
+
+const TEMPLATE = path.join(__dirname, '..', '..', 'templates', 'contract.md.tmpl');
+
+function contractsDir(cwd) {
+  return path.join(cwd, 'contracts');
+}
+
+function create(cwd, name) {
+  if (!name) {
+    throw new Error('contract new requires a name');
+  }
+  const v = validateSlug(name);
+  if (!v.valid) {
+    throw new Error(`invalid contract name "${name}": ${v.issues.join('; ')}`);
+  }
+  const file = path.join(contractsDir(cwd), `${name}.md`);
+  if (fs.existsSync(file)) {
+    throw new Error(
+      `contract "${name}" already exists — contracts are frozen; a change is a NEW contract, not an edit`,
+    );
+  }
+  fs.mkdirSync(contractsDir(cwd), { recursive: true });
+  fs.writeFileSync(file, render(fs.readFileSync(TEMPLATE, 'utf8'), { name }));
+  return { name, path: file };
+}
+
+function list(cwd) {
+  const dir = contractsDir(cwd);
+  const contracts = fs.existsSync(dir)
+    ? fs
+        .readdirSync(dir)
+        .filter((n) => n.endsWith('.md'))
+        .sort()
+    : [];
+  return { contracts };
+}
+
+function dispatch(args, flags) {
+  const cwd = flags.cwd || process.cwd();
+  const verb = args[0];
+  if (verb === 'new') {
+    return create(cwd, args[1]);
+  }
+  if (verb === 'list') {
+    return list(cwd);
+  }
+  throw new Error(`unknown contract verb: ${verb || '(none)'} — use new|list`);
+}
+
+module.exports = { contractsDir, create, list, dispatch };

package/verity/bin/lib/core.cjs

@@ -0,0 +1,63 @@
+// Verity core utilities (the seed of the `identity` command, Role 1 / Vision).
+//
+// validateSlug enforces the UNION of downstream constraints the slug must satisfy,
+// because it becomes the identity key threaded through repo name, package name,
+// container-registry image path, DNS label, branch names, env names, and secret
+// names (see framework-spec.md §4.1). The strictest common denominator is:
+// lowercase, hyphen-separated, starts with a letter, no underscores, <= 63 chars.
+
+function validateSlug(slug) {
+  const issues = [];
+  const s = String(slug ?? '');
+
+  if (s.length === 0) {
+    issues.push('empty');
+  }
+  if (s.length > 63) {
+    issues.push('too long (max 63 chars — DNS label limit)');
+  }
+  if (!/^[a-z]/.test(s)) {
+    issues.push('must start with a lowercase letter');
+  }
+  if (/[A-Z]/.test(s)) {
+    issues.push('no uppercase (container/package registries require lowercase)');
+  }
+  if (s.includes('_')) {
+    issues.push('no underscores (DNS/registry-unsafe)');
+  }
+  if (!/^[a-z0-9-]*$/.test(s)) {
+    issues.push('only lowercase letters, digits, and hyphens allowed');
+  }
+  if (/--/.test(s)) {
+    issues.push('no consecutive hyphens');
+  }
+  if (/-$/.test(s)) {
+    issues.push('must not end with a hyphen');
+  }
+
+  return { valid: issues.length === 0, issues };
+}
+
+// Turn arbitrary text into a slug candidate (lowercase, hyphen-joined, trimmed,
+// capped at 63). The result may still fail validateSlug (e.g. a leading digit) —
+// the caller validates and surfaces issues; this only proposes.
+function generateSlug(text) {
+  return String(text ?? '')
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+/, '')
+    .replace(/-+$/, '')
+    .slice(0, 63)
+    .replace(/-+$/, '');
+}
+
+// Render a template: replace {{key}} (word chars only, no spaces) so GitHub Actions
+// ${{ ... }} expressions — which always contain spaces/dots — pass through untouched.
+function render(tmpl, vars) {
+  return String(tmpl).replace(/\{\{(\w+)\}\}/g, (match, key) =>
+    key in vars ? String(vars[key] ?? '') : match,
+  );
+}
+
+module.exports = { validateSlug, generateSlug, render };

package/verity/bin/lib/golive.cjs

@@ -0,0 +1,49 @@
+// Pre-go-live / first-real-data gate (framework-spec.md §6). A BLOCKING checklist
+// before the project accepts real data/users (Security Auditor + SRE jointly). Auto-
+// checks what's derivable; lists the manual gates that need human confirmation.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const security = require('./security.cjs');
+const status = require('./status.cjs');
+
+function check(cwd) {
+  const runtime = status.read(cwd);
+  const items = [
+    {
+      item: 'Security invariants defined (docs/security-invariants.md)',
+      ok: Boolean(security.read(cwd)),
+    },
+    {
+      item: 'Secret locations recorded in STATUS (runtime.json)',
+      ok: Array.isArray(runtime.secret_locations) && runtime.secret_locations.length > 0,
+    },
+    {
+      item: 'Recovery plan present (recovery-plan.md)',
+      ok: fs.existsSync(path.join(cwd, 'recovery-plan.md')),
+    },
+  ];
+  const manual = [
+    'Secrets rotated (no dev/exposed credentials)',
+    'Throwaway accounts removed',
+    'Cross-user data isolation verified',
+    'Backup coverage for ALL persistent state (no silent gaps)',
+    'Security deep-audit sign-off',
+  ];
+  const autoPass = items.every((i) => i.ok);
+  return {
+    items,
+    manual,
+    autoPass,
+    ready: autoPass,
+    raw: autoPass
+      ? 'auto-checks pass — now confirm the manual gates before go-live'
+      : 'BLOCKED: resolve the failing auto-checks',
+  };
+}
+
+function dispatch(args, flags) {
+  return check(flags.cwd || process.cwd());
+}
+
+module.exports = { check, dispatch };

package/verity/bin/lib/handoff.cjs

@@ -0,0 +1,72 @@
+// Technical Writer (framework-spec.md §6, Role 13) — handoff briefs in docs/handoff/.
+// The brief's highest-leverage element is the "settled decisions — do NOT re-litigate"
+// section (H6); the reading-order README is what makes zero-setup rejoin real (H5).
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { validateSlug, render } = require('./core.cjs');
+
+const README_TEMPLATE = path.join(__dirname, '..', '..', 'templates', 'handoff-readme.md.tmpl');
+const BRIEF_TEMPLATE = path.join(__dirname, '..', '..', 'templates', 'handoff-brief.md.tmpl');
+
+function handoffDir(cwd) {
+  return path.join(cwd, 'docs', 'handoff');
+}
+
+function ensureReadme(cwd) {
+  const p = path.join(handoffDir(cwd), 'README.md');
+  if (fs.existsSync(p)) {
+    return { created: false, path: p };
+  }
+  fs.mkdirSync(handoffDir(cwd), { recursive: true });
+  fs.writeFileSync(p, fs.readFileSync(README_TEMPLATE, 'utf8'));
+  return { created: true, path: p };
+}
+
+function create(cwd, slug, opts = {}) {
+  if (!slug) {
+    throw new Error('handoff new requires a slug');
+  }
+  const v = validateSlug(slug);
+  if (!v.valid) {
+    throw new Error(`invalid handoff slug "${slug}": ${v.issues.join('; ')}`);
+  }
+  ensureReadme(cwd);
+  const p = path.join(handoffDir(cwd), `${slug}.md`);
+  if (fs.existsSync(p) && !opts.force) {
+    throw new Error(`handoff brief "${slug}" already exists`);
+  }
+  fs.writeFileSync(
+    p,
+    render(fs.readFileSync(BRIEF_TEMPLATE, 'utf8'), { slug, title: opts.title || slug }),
+  );
+  return { created: true, path: p };
+}
+
+function list(cwd) {
+  const dir = handoffDir(cwd);
+  const briefs = fs.existsSync(dir)
+    ? fs
+        .readdirSync(dir)
+        .filter((n) => n.endsWith('.md') && n !== 'README.md')
+        .sort()
+    : [];
+  return { briefs };
+}
+
+function dispatch(args, flags) {
+  const cwd = flags.cwd || process.cwd();
+  const verb = args[0];
+  if (verb === 'new') {
+    return create(cwd, args[1], { title: flags.title, force: Boolean(flags.force) });
+  }
+  if (verb === 'list') {
+    return list(cwd);
+  }
+  if (verb === 'readme') {
+    return ensureReadme(cwd);
+  }
+  throw new Error(`unknown handoff verb: ${verb || '(none)'} — use new|list|readme`);
+}
+
+module.exports = { handoffDir, ensureReadme, create, list, dispatch };

package/verity/bin/lib/identity.cjs

@@ -0,0 +1,112 @@
+// Verity identity manifest — `.verity/identity.json` (framework-spec.md §4.1).
+// The slug is the identity key threaded through repo/package/image/dns/env/secret
+// names. It is LOCKED ONCE and immutable; renaming later is a migration, not an edit.
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { validateSlug } = require('./core.cjs');
+
+function manifestPath(cwd) {
+  return path.join(cwd, '.verity', 'identity.json');
+}
+
+// Default command runner: exit 0 → { ok: true }, anything else → { ok: false }.
+// Injectable so availability checks (which shell out to gh/npm) stay unit-testable.
+function defaultRun(cmd, args) {
+  try {
+    execFileSync(cmd, args, { stdio: 'pipe' });
+    return { ok: true };
+  } catch {
+    return { ok: false };
+  }
+}
+
+// Best-effort availability: a successful lookup means the name is TAKEN.
+// Caveat: a network/auth failure also returns non-zero, so "available" can be a
+// false positive — surfaced as best-effort, not a guarantee.
+function checkAvailability(slug, opts) {
+  const run = opts.run || defaultRun;
+  const checks = {};
+  checks.npm = { available: !run('npm', ['view', slug, 'version']).ok };
+  if (opts.owner) {
+    checks.github = {
+      available: !run('gh', ['repo', 'view', `${opts.owner}/${slug}`]).ok,
+    };
+  }
+  return checks;
+}
+
+function check(slug, opts = {}) {
+  const validation = validateSlug(slug);
+  const availability = validation.valid ? checkAvailability(slug, opts) : {};
+  const values = Object.values(availability).map((c) => c.available);
+  const available = values.length > 0 ? values.every(Boolean) : null;
+  return {
+    slug,
+    valid: validation.valid,
+    issues: validation.issues,
+    availability,
+    available,
+  };
+}
+
+function lock(cwd, opts) {
+  const { name, slug, owner, force } = opts;
+  const p = manifestPath(cwd);
+  if (fs.existsSync(p) && !force) {
+    throw new Error(
+      `identity already locked at ${p} — renaming is a migration, not an edit (use --force to override)`,
+    );
+  }
+  const v = validateSlug(slug);
+  if (!v.valid) {
+    throw new Error(`invalid slug "${slug}": ${v.issues.join('; ')}`);
+  }
+  const manifest = {
+    version: '1.0',
+    name: name || slug,
+    slug,
+    owner: owner || null,
+    image_prefix: owner ? `ghcr.io/${owner}/${slug}` : null,
+    locked_at: new Date().toISOString(),
+  };
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, `${JSON.stringify(manifest, null, 2)}\n`);
+  return { locked: true, path: p, manifest };
+}
+
+function get(cwd, key) {
+  const p = manifestPath(cwd);
+  if (!fs.existsSync(p)) {
+    throw new Error(`no identity manifest at ${p} — run 'verity identity lock' first`);
+  }
+  const manifest = JSON.parse(fs.readFileSync(p, 'utf8'));
+  if (!key) {
+    return { manifest };
+  }
+  const value = manifest[key];
+  return { key, value, raw: value === null || value === undefined ? '' : String(value) };
+}
+
+function dispatch(args, flags) {
+  const verb = args[0];
+  const cwd = flags.cwd || process.cwd();
+  if (verb === 'check') {
+    return check(args[1], { owner: flags.owner });
+  }
+  if (verb === 'lock') {
+    return lock(cwd, {
+      name: args[1],
+      slug: args[2],
+      owner: flags.owner,
+      force: Boolean(flags.force),
+    });
+  }
+  if (verb === 'get') {
+    return get(cwd, args[1]);
+  }
+  throw new Error(`unknown identity verb: ${verb || '(none)'} — use check|lock|get`);
+}
+
+module.exports = { manifestPath, check, checkAvailability, lock, get, dispatch };