@elevasis/core 0.5.0 → 0.7.0

package/src/scaffold-registry/__tests__/schema.test.ts

@@ -0,0 +1,280 @@
+import { describe, expect, it } from 'vitest'
+import { ScaffoldEntryKindSchema, ScaffoldRegistryEntrySchema, ScaffoldRegistrySchema } from '../schema'
+
+// ---------------------------------------------------------------------------
+// Kind enum
+// ---------------------------------------------------------------------------
+
+describe('ScaffoldEntryKindSchema', () => {
+  it('accepts all declared kinds', () => {
+    const validKinds = [
+      'autogen',
+      'manual-scaffold',
+      'typed-id',
+      'sync-preservation',
+      'vibe-gated',
+      'sdk-cli-generator',
+      'validator',
+      'other'
+    ]
+    for (const kind of validKinds) {
+      expect(ScaffoldEntryKindSchema.safeParse(kind).success).toBe(true)
+    }
+  })
+
+  it('rejects unknown kinds', () => {
+    const result = ScaffoldEntryKindSchema.safeParse('unknown-kind')
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects empty string', () => {
+    expect(ScaffoldEntryKindSchema.safeParse('').success).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Valid full entry
+// ---------------------------------------------------------------------------
+
+const validEntry = {
+  id: 'business-directory-rename',
+  kind: 'manual-scaffold',
+  owner: 'packages/core',
+  sources: ['packages/core/src/business/**'],
+  dependents: [
+    {
+      path: '.navigation/_generated/skeleton.md',
+      regen: 'pnpm navigation:generate',
+      kind: 'autogen',
+      hint: 'Regenerate after rename.'
+    }
+  ]
+}
+
+describe('ScaffoldRegistryEntrySchema — valid entry', () => {
+  it('parses a complete valid entry', () => {
+    const result = ScaffoldRegistryEntrySchema.safeParse(validEntry)
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.id).toBe('business-directory-rename')
+      expect(result.data.kind).toBe('manual-scaffold')
+      expect(result.data.sources).toHaveLength(1)
+      expect(result.data.dependents).toHaveLength(1)
+    }
+  })
+
+  it('accepts optional notes and cooldown_ms', () => {
+    const withOptionals = {
+      ...validEntry,
+      notes: 'Extra context here.',
+      cooldown_ms: 60_000
+    }
+    const result = ScaffoldRegistryEntrySchema.safeParse(withOptionals)
+    expect(result.success).toBe(true)
+  })
+
+  it('accepts optional regen command when provided', () => {
+    const withRegen = { ...validEntry, regen: 'pnpm navigation:generate' }
+    const result = ScaffoldRegistryEntrySchema.safeParse(withRegen)
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.regen).toBe('pnpm navigation:generate')
+    }
+  })
+
+  it('accepts entry without regen field (optional)', () => {
+    const result = ScaffoldRegistryEntrySchema.safeParse(validEntry)
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.regen).toBeUndefined()
+    }
+  })
+
+  it('rejects regen as empty string', () => {
+    const withEmptyRegen = { ...validEntry, regen: '' }
+    const result = ScaffoldRegistryEntrySchema.safeParse(withEmptyRegen)
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects regen as non-string (number)', () => {
+    const withBadRegen = { ...validEntry, regen: 42 }
+    const result = ScaffoldRegistryEntrySchema.safeParse(withBadRegen)
+    expect(result.success).toBe(false)
+  })
+
+  it('accepts entry without optional hint / regen in dependent', () => {
+    const minimalDependent = {
+      ...validEntry,
+      dependents: [{ path: 'some/path' }]
+    }
+    expect(ScaffoldRegistryEntrySchema.safeParse(minimalDependent).success).toBe(true)
+  })
+
+  it('accepts auto_regen: true', () => {
+    const withAutoRegen = { ...validEntry, auto_regen: true }
+    expect(ScaffoldRegistryEntrySchema.safeParse(withAutoRegen).success).toBe(true)
+  })
+
+  it('accepts auto_regen: false', () => {
+    const withAutoRegen = { ...validEntry, auto_regen: false }
+    expect(ScaffoldRegistryEntrySchema.safeParse(withAutoRegen).success).toBe(true)
+  })
+
+  it('accepts entry without auto_regen (optional)', () => {
+    expect(ScaffoldRegistryEntrySchema.safeParse(validEntry).success).toBe(true)
+  })
+
+  it('rejects auto_regen as a non-boolean', () => {
+    const withBadAutoRegen = { ...validEntry, auto_regen: 'yes' }
+    expect(ScaffoldRegistryEntrySchema.safeParse(withBadAutoRegen).success).toBe(false)
+  })
+
+  it('parses all six seed-entry kinds', () => {
+    const kinds = ['autogen', 'manual-scaffold', 'typed-id', 'sync-preservation', 'vibe-gated', 'validator']
+    for (const kind of kinds) {
+      const result = ScaffoldRegistryEntrySchema.safeParse({ ...validEntry, kind })
+      expect(result.success, `kind ${kind} should parse`).toBe(true)
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Invalid entries — required fields missing
+// ---------------------------------------------------------------------------
+
+describe('ScaffoldRegistryEntrySchema — invalid entries', () => {
+  it('rejects entry missing id', () => {
+    const { id: _id, ...withoutId } = validEntry
+    expect(ScaffoldRegistryEntrySchema.safeParse(withoutId).success).toBe(false)
+  })
+
+  it('rejects entry missing kind', () => {
+    const { kind: _kind, ...withoutKind } = validEntry
+    expect(ScaffoldRegistryEntrySchema.safeParse(withoutKind).success).toBe(false)
+  })
+
+  it('rejects entry missing owner', () => {
+    const { owner: _owner, ...withoutOwner } = validEntry
+    expect(ScaffoldRegistryEntrySchema.safeParse(withoutOwner).success).toBe(false)
+  })
+
+  it('rejects entry missing sources', () => {
+    const { sources: _sources, ...withoutSources } = validEntry
+    expect(ScaffoldRegistryEntrySchema.safeParse(withoutSources).success).toBe(false)
+  })
+
+  it('rejects entry missing dependents', () => {
+    const { dependents: _dependents, ...withoutDependents } = validEntry
+    expect(ScaffoldRegistryEntrySchema.safeParse(withoutDependents).success).toBe(false)
+  })
+
+  it('rejects invalid kind', () => {
+    const withBadKind = { ...validEntry, kind: 'not-a-real-kind' }
+    const result = ScaffoldRegistryEntrySchema.safeParse(withBadKind)
+    expect(result.success).toBe(false)
+  })
+
+  it('rejects id with uppercase characters', () => {
+    const withBadId = { ...validEntry, id: 'BusinessDirectoryRename' }
+    expect(ScaffoldRegistryEntrySchema.safeParse(withBadId).success).toBe(false)
+  })
+
+  it('rejects id with spaces', () => {
+    const withBadId = { ...validEntry, id: 'business directory rename' }
+    expect(ScaffoldRegistryEntrySchema.safeParse(withBadId).success).toBe(false)
+  })
+
+  it('rejects empty sources array', () => {
+    const withEmptySources = { ...validEntry, sources: [] }
+    expect(ScaffoldRegistryEntrySchema.safeParse(withEmptySources).success).toBe(false)
+  })
+
+  it('rejects empty dependents array', () => {
+    const withEmptyDependents = { ...validEntry, dependents: [] }
+    expect(ScaffoldRegistryEntrySchema.safeParse(withEmptyDependents).success).toBe(false)
+  })
+
+  it('rejects dependent missing path', () => {
+    const withBadDependent = {
+      ...validEntry,
+      dependents: [{ regen: 'pnpm nav' }]
+    }
+    expect(ScaffoldRegistryEntrySchema.safeParse(withBadDependent).success).toBe(false)
+  })
+
+  it('rejects negative cooldown_ms', () => {
+    const withBadCooldown = { ...validEntry, cooldown_ms: -1 }
+    expect(ScaffoldRegistryEntrySchema.safeParse(withBadCooldown).success).toBe(false)
+  })
+
+  it('rejects non-integer cooldown_ms', () => {
+    const withBadCooldown = { ...validEntry, cooldown_ms: 300.5 }
+    expect(ScaffoldRegistryEntrySchema.safeParse(withBadCooldown).success).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Top-level registry document
+// ---------------------------------------------------------------------------
+
+describe('ScaffoldRegistrySchema', () => {
+  const validRegistry = {
+    version: '1',
+    entries: [validEntry]
+  }
+
+  it('parses a valid registry document', () => {
+    const result = ScaffoldRegistrySchema.safeParse(validRegistry)
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.version).toBe('1')
+      expect(result.data.entries).toHaveLength(1)
+    }
+  })
+
+  it('applies default version when omitted', () => {
+    const withoutVersion = { entries: [validEntry] }
+    const result = ScaffoldRegistrySchema.safeParse(withoutVersion)
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.version).toBe('1')
+    }
+  })
+
+  it('rejects registry with no entries', () => {
+    const empty = { version: '1', entries: [] }
+    expect(ScaffoldRegistrySchema.safeParse(empty).success).toBe(false)
+  })
+
+  it('rejects registry missing entries key', () => {
+    expect(ScaffoldRegistrySchema.safeParse({ version: '1' }).success).toBe(false)
+  })
+
+  it('accepts multiple entries of different kinds', () => {
+    const multiEntry = {
+      version: '1',
+      entries: [
+        validEntry,
+        {
+          id: 'meta-json-updated',
+          kind: 'validator',
+          owner: 'apps/docs',
+          sources: ['apps/docs/content/docs/**/meta.json'],
+          dependents: [{ path: '(self)', regen: 'pnpm check-docs-meta' }]
+        },
+        {
+          id: 'external-template-hook-added',
+          kind: 'sync-preservation',
+          owner: 'external/_template',
+          sources: ['external/_template/.claude/hooks/*.mjs'],
+          dependents: [{ path: 'external/_template/.claude/settings.json', regen: 'manual' }]
+        }
+      ]
+    }
+    const result = ScaffoldRegistrySchema.safeParse(multiEntry)
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.entries).toHaveLength(3)
+    }
+  })
+})

package/src/scaffold-registry/index.ts

@@ -0,0 +1,194 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { parse as parseYaml } from 'yaml'
+import { type ScaffoldRegistry, type ScaffoldRegistryEntry, ScaffoldRegistrySchema } from './schema'
+
+export { ScaffoldRegistrySchema, ScaffoldEntryKindSchema } from './schema'
+export type { ScaffoldRegistry, ScaffoldRegistryEntry, ScaffoldRef, ScaffoldEntryKind } from './schema'
+
+// ---------------------------------------------------------------------------
+// Paths (resolved relative to the monorepo root, not this file's location)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a path relative to the monorepo root.
+ * Works whether this module is running from packages/core/src or from dist/.
+ */
+function monorepoRoot(): string {
+  // Walk up from __dirname until we find the .claude directory (monorepo marker)
+  const { dirname } = path
+  let dir = __dirname
+  for (let i = 0; i < 8; i++) {
+    try {
+      readFileSync(path.join(dir, '.claude', 'settings.json'))
+      return dir
+    } catch {
+      dir = dirname(dir)
+    }
+  }
+  throw new Error(
+    'scaffold-registry: could not locate monorepo root (no .claude/settings.json found in ancestor directories)'
+  )
+}
+
+const YAML_FILENAME = '.claude/scaffold-registry.yml'
+const JSON_FILENAME = '.claude/scaffold-registry.compiled.json'
+
+// ---------------------------------------------------------------------------
+// Load + validate
+// ---------------------------------------------------------------------------
+
+/**
+ * Load and Zod-validate the scaffold registry from `.claude/scaffold-registry.yml`.
+ *
+ * Throws if:
+ * - The YAML file is missing or unreadable
+ * - The YAML fails Zod validation
+ * - The compiled JSON is present but its `entries` count differs from the YAML
+ *   (drift detection — regenerate with `compileScaffoldRegistry()` to fix)
+ */
+export function loadScaffoldRegistry(): ScaffoldRegistry {
+  const root = monorepoRoot()
+  const yamlPath = path.join(root, YAML_FILENAME)
+
+  let raw: string
+  try {
+    raw = readFileSync(yamlPath, 'utf-8')
+  } catch (err) {
+    throw new Error(`scaffold-registry: could not read ${YAML_FILENAME} — ${String(err)}`)
+  }
+
+  const parsed = parseYaml(raw) as unknown
+  const result = ScaffoldRegistrySchema.safeParse(parsed)
+
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `  [${i.path.join('.')}] ${i.message}`).join('\n')
+    throw new Error(`scaffold-registry: YAML validation failed:\n${issues}`)
+  }
+
+  const registry = result.data
+
+  // Drift check: if compiled JSON exists, verify entry count matches
+  const jsonPath = path.join(root, JSON_FILENAME)
+  try {
+    const compiledRaw = readFileSync(jsonPath, 'utf-8')
+    const compiled = JSON.parse(compiledRaw) as { entries?: unknown[] }
+    if (compiled.entries?.length !== registry.entries.length) {
+      throw new Error(
+        `scaffold-registry: compiled JSON is out of sync with YAML ` +
+          `(YAML has ${registry.entries.length} entries, JSON has ${compiled.entries?.length ?? 0}). ` +
+          `Run compileScaffoldRegistry() to regenerate.`
+      )
+    }
+  } catch (err) {
+    // If the file doesn't exist, skip drift check silently (first-run scenario)
+    if ((err as { code?: string }).code !== 'ENOENT') {
+      throw err
+    }
+  }
+
+  return registry
+}
+
+// ---------------------------------------------------------------------------
+// Compile
+// ---------------------------------------------------------------------------
+
+/**
+ * Load, validate, and write the pre-compiled JSON lookup file.
+ * Run this whenever `.claude/scaffold-registry.yml` changes.
+ *
+ * Called by the `pnpm scaffold:compile-registry` script (wired in Step 2 CI).
+ */
+export function compileScaffoldRegistry(): ScaffoldRegistry {
+  const root = monorepoRoot()
+  const registry = loadScaffoldRegistryNoSyncCheck(root)
+
+  const jsonPath = path.join(root, JSON_FILENAME)
+  writeFileSync(jsonPath, JSON.stringify(registry, null, 2) + '\n', 'utf-8')
+
+  return registry
+}
+
+// ---------------------------------------------------------------------------
+// Lookup helpers (used by hooks for fast path matching)
+// ---------------------------------------------------------------------------
+
+/**
+ * Load from the pre-compiled JSON only (fastest path; used by PostToolUse hooks).
+ * Falls back to YAML if the JSON is missing.
+ */
+export function loadScaffoldRegistryFast(): ScaffoldRegistry {
+  const root = monorepoRoot()
+  const jsonPath = path.join(root, JSON_FILENAME)
+
+  try {
+    const raw = readFileSync(jsonPath, 'utf-8')
+    const parsed = JSON.parse(raw) as unknown
+    const result = ScaffoldRegistrySchema.safeParse(parsed)
+    if (result.success) return result.data
+  } catch {
+    // fall through to YAML
+  }
+
+  return loadScaffoldRegistryNoSyncCheck(root)
+}
+
+/**
+ * Return all entries whose `sources` contain at least one pattern that matches
+ * the given file path. Pattern matching is a simple substring/glob-prefix check
+ * suitable for hook use; Step 3 will upgrade to full micromatch when the hook
+ * is implemented.
+ */
+export function findMatchingEntries(registry: ScaffoldRegistry, filePath: string): ScaffoldRegistryEntry[] {
+  return registry.entries.filter((entry) => entry.sources.some((pattern) => pathMatchesPattern(filePath, pattern)))
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function loadScaffoldRegistryNoSyncCheck(root: string): ScaffoldRegistry {
+  const yamlPath = path.join(root, YAML_FILENAME)
+  let raw: string
+  try {
+    raw = readFileSync(yamlPath, 'utf-8')
+  } catch (err) {
+    throw new Error(`scaffold-registry: could not read ${YAML_FILENAME} — ${String(err)}`)
+  }
+  const parsed = parseYaml(raw) as unknown
+  const result = ScaffoldRegistrySchema.safeParse(parsed)
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `  [${i.path.join('.')}] ${i.message}`).join('\n')
+    throw new Error(`scaffold-registry: YAML validation failed:\n${issues}`)
+  }
+  return result.data
+}
+
+/**
+ * Lightweight pattern match: handles exact paths, directory prefixes, and
+ * simple `*` wildcards at the end of a segment. Full micromatch lands in Step 3.
+ */
+function pathMatchesPattern(filePath: string, pattern: string): boolean {
+  // Normalize separators
+  const normalizedFile = filePath.replace(/\\/g, '/')
+  const normalizedPattern = pattern.replace(/\\/g, '/')
+
+  // Exact match
+  if (normalizedFile === normalizedPattern) return true
+
+  // If pattern ends with `/**` or `/*`, check prefix
+  if (normalizedPattern.endsWith('/**') || normalizedPattern.endsWith('/*')) {
+    const prefix = normalizedPattern.slice(0, normalizedPattern.lastIndexOf('/*'))
+    return normalizedFile.startsWith(prefix + '/')
+  }
+
+  // If pattern contains `*`, convert to simple regex
+  if (normalizedPattern.includes('*')) {
+    const escaped = normalizedPattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*')
+    return new RegExp(`^${escaped}$`).test(normalizedFile)
+  }
+
+  // Directory prefix match (pattern is a directory)
+  return normalizedFile.startsWith(normalizedPattern + '/')
+}

package/src/scaffold-registry/schema.ts

@@ -0,0 +1,144 @@
+import { z } from 'zod'
+
+// ---------------------------------------------------------------------------
+// Kind taxonomy
+// ---------------------------------------------------------------------------
+
+/**
+ * The kind of scaffold entry:
+ *
+ * - autogen: fully derivable from source; regen command is the fix
+ * - manual-scaffold: hand-authored structure that must be updated on source change
+ * - typed-id: typed-ID constants that encode semantic naming decisions
+ * - sync-preservation: external-template files with a declared sync tier
+ * - vibe-gated: paths protected by the pre-edit-vibe-gate hook
+ * - sdk-cli-generator: SDK CLI generators (generate-docs-index, generate-resources, etc.)
+ * - validator: drift-detection scripts or CI checks (meta.json pages[] validators, etc.)
+ * - other: escape hatch; requires free-form notes
+ */
+export const ScaffoldEntryKindSchema = z.enum([
+  'autogen',
+  'manual-scaffold',
+  'typed-id',
+  'sync-preservation',
+  'vibe-gated',
+  'sdk-cli-generator',
+  'validator',
+  'other'
+])
+
+export type ScaffoldEntryKind = z.infer<typeof ScaffoldEntryKindSchema>
+
+// ---------------------------------------------------------------------------
+// Scaffold reference (a single downstream artifact that needs attention)
+// ---------------------------------------------------------------------------
+
+export const ScaffoldRefSchema = z.object({
+  /**
+   * File path, glob, or symbolic target (e.g. "docs: sync-preservation-matrix").
+   * Symbolic targets begin with "docs:" or "autogen-target:".
+   */
+  path: z.string().min(1),
+
+  /**
+   * Command to regenerate, or "manual" if human judgment is required.
+   */
+  regen: z.string().min(1).optional(),
+
+  /**
+   * Optionally narrow the kind of this specific scaffold reference, when it
+   * differs from the parent entry's kind.
+   */
+  kind: ScaffoldEntryKindSchema.optional(),
+
+  /**
+   * Human-readable hint shown in reminder messages.
+   */
+  hint: z.string().optional()
+})
+
+export type ScaffoldRef = z.infer<typeof ScaffoldRefSchema>
+
+// ---------------------------------------------------------------------------
+// Registry entry
+// ---------------------------------------------------------------------------
+
+export const ScaffoldRegistryEntrySchema = z.object({
+  /**
+   * Stable slug identifier for this entry (kebab-case).
+   * Referenced by hooks, CI checks, and the /scaffold verify skill.
+   */
+  id: z
+    .string()
+    .min(1)
+    .regex(/^[a-z0-9-]+$/, 'id must be kebab-case'),
+
+  /**
+   * The primary kind of this entry.
+   */
+  kind: ScaffoldEntryKindSchema,
+
+  /**
+   * Glob patterns (or exact paths) that, when edited, should trigger a
+   * reminder for the associated scaffolds. Uses micromatch / glob semantics.
+   */
+  sources: z.array(z.string().min(1)).min(1, 'At least one source pattern is required'),
+
+  /**
+   * Downstream artifacts that need attention when a source changes.
+   */
+  dependents: z.array(ScaffoldRefSchema).min(1, 'At least one dependent is required'),
+
+  /**
+   * Package or app path that owns this scaffold surface.
+   * Examples: "packages/core", "apps/api", "external/_template"
+   */
+  owner: z.string().min(1),
+
+  /**
+   * Free-form notes. Required when kind is "other".
+   */
+  notes: z.string().optional(),
+
+  /**
+   * The shell command used to regenerate this entry's outputs.
+   *
+   * Required for `kind: autogen` entries once Step 6 migration lands.
+   * Optional now so harness scaffolding (Step 5) can land before migrating
+   * existing generators. Validated as a non-empty string when present.
+   *
+   * Example: `"pnpm navigation:generate"`, `"pnpm scaffold:sync"`
+   */
+  regen: z.string().min(1).optional(),
+
+  /**
+   * Per-entry reminder throttle override in milliseconds.
+   * Defaults to the hook-level default (5 minutes = 300_000 ms) when omitted.
+   */
+  cooldown_ms: z.number().int().positive().optional(),
+
+  /**
+   * When true, the PostToolUse reminder hook will automatically run the `regen`
+   * command after emitting the reminder, rather than just advising the user.
+   * Defaults to false (advisory only). Only meaningful when `regen` is also set.
+   */
+  auto_regen: z.boolean().optional()
+})
+
+export type ScaffoldRegistryEntry = z.infer<typeof ScaffoldRegistryEntrySchema>
+
+// ---------------------------------------------------------------------------
+// Top-level registry document
+// ---------------------------------------------------------------------------
+
+export const ScaffoldRegistrySchema = z.object({
+  /**
+   * Schema version for forward-compatibility detection.
+   * Bump when the shape changes in a breaking way.
+   */
+  version: z.string().default('1'),
+
+  entries: z.array(ScaffoldRegistryEntrySchema).min(1)
+})
+
+export type ScaffoldRegistry = z.infer<typeof ScaffoldRegistrySchema>