@elevasis/core 0.7.0 → 0.8.0

package/src/scaffold-registry/schema.ts

@@ -1,144 +1,212 @@
-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
- */
+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'
-])
+  'vibe-gated',
+  'sdk-cli-generator',
+  'validator',
+  'other'
+])
 
 export type ScaffoldEntryKind = z.infer<typeof ScaffoldEntryKindSchema>
 
 // ---------------------------------------------------------------------------
-// Scaffold reference (a single downstream artifact that needs attention)
+// External sync taxonomy
 // ---------------------------------------------------------------------------
 
-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 const ExternalSyncCategorySchema = z.enum(['replace', 'merge', 'never-touch', 'generated'])
 
-export type ScaffoldRef = z.infer<typeof ScaffoldRefSchema>
+export type ExternalSyncCategory = z.infer<typeof ExternalSyncCategorySchema>
 
-// ---------------------------------------------------------------------------
-// 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 ExternalSyncOwnerSchema = z.enum([
+  'template',
+  '@elevasis/ui',
+  '@elevasis/core',
+  '@elevasis/sdk',
+  'generator',
+  'project'
+])
 
-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'),
+export type ExternalSyncOwner = z.infer<typeof ExternalSyncOwnerSchema>
 
-  entries: z.array(ScaffoldRegistryEntrySchema).min(1)
-})
+export const ExternalSyncStrategySchema = z.enum([
+  'replace-all',
+  'merge-regions',
+  'merge-baseline',
+  'verify-only',
+  'generated-freshness'
+])
 
-export type ScaffoldRegistry = z.infer<typeof ScaffoldRegistrySchema>
+export type ExternalSyncStrategy = z.infer<typeof ExternalSyncStrategySchema>
+
+export const ExternalSyncDeletePolicySchema = z.enum(['none', 'manifest-only'])
+
+export type ExternalSyncDeletePolicy = z.infer<typeof ExternalSyncDeletePolicySchema>
+
+// ---------------------------------------------------------------------------
+// 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"
+     *
+     * External-sync-aware entries still use this field, but are constrained to
+     * the `ExternalSyncOwnerSchema` enum when any external sync metadata is set.
+     */
+    owner: z.string().min(1),
+
+    /**
+     * Optional external sync classification for entries that participate in the
+     * external template ownership model.
+     */
+    category: ExternalSyncCategorySchema.optional(),
+
+    /**
+     * Optional external sync strategy used by compare/apply/verify tooling.
+     */
+    strategy: ExternalSyncStrategySchema.optional(),
+
+    /**
+     * Optional delete behavior for managed external sync surfaces.
+     */
+    delete_policy: ExternalSyncDeletePolicySchema.optional(),
+
+    /**
+     * 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()
+  })
+  .superRefine((entry, ctx) => {
+    const usesExternalSyncMetadata =
+      entry.category !== undefined || entry.strategy !== undefined || entry.delete_policy !== undefined
+
+    if (usesExternalSyncMetadata) {
+      const ownerResult = ExternalSyncOwnerSchema.safeParse(entry.owner)
+      if (!ownerResult.success) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['owner'],
+          message: `owner must be one of ${ExternalSyncOwnerSchema.options.join(', ')} when external sync metadata is set`
+        })
+      }
+    }
+  })
+
+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>