Merge pull request #6 from tokenhost/feat/schema-migrations

SPEC 6: schema migrations framework + real th migrate

Author: snissn

packages/cli/src/index.ts

@@ -12,6 +12,8 @@ import {
   computeSchemaHash,
   importLegacyContractsJson,
   lintThs,
+  listThsMigrations,
+  migrateThsSchema,
   validateThsStructural,
   type Issue,
   type ThsSchema
@@ -1283,10 +1285,71 @@ program
 program
   .command('migrate')
   .argument('<schema>', 'Path to THS schema JSON file')
-  .description('Apply schema migrations locally (stub)')
-  .action(() => {
-    console.error('th migrate is not implemented yet (no migrations registry wired).');
-    process.exitCode = 1;
+  .description('Apply local THS schema migrations')
+  .option('--list', 'List known migrations and exit', false)
+  .option('--down', 'Apply down migrations (revert)', false)
+  .option('--steps <n>', 'Number of migrations to apply (default: all for up; 1 for down)')
+  .option('--in-place', 'Overwrite the input schema file', false)
+  .option('--out <file>', 'Write migrated schema JSON to a file (defaults to stdout)')
+  .action((schemaPath: string, opts: { list: boolean; down: boolean; steps?: string; inPlace: boolean; out?: string }) => {
+    if (opts.list) {
+      const migrations = listThsMigrations();
+      for (const m of migrations) {
+        console.log(`${m.id} - ${m.description}`);
+      }
+      return;
+    }
+
+    if (opts.inPlace && opts.out) {
+      console.error('ERROR: --in-place and --out are mutually exclusive.');
+      process.exitCode = 1;
+      return;
+    }
+
+    const input = readJsonFile(schemaPath);
+    const structural = validateThsStructural(input);
+    if (!structural.ok) {
+      console.error(formatIssues(structural.issues));
+      process.exitCode = 1;
+      return;
+    }
+
+    const schema = structural.data!;
+
+    const steps = (() => {
+      if (typeof opts.steps !== 'string' || opts.steps.trim() === '') return undefined;
+      const n = Number(opts.steps);
+      if (!Number.isFinite(n) || n < 0) throw new Error('Invalid --steps value. Expected a non-negative number.');
+      return Math.floor(n);
+    })();
+
+    const direction = opts.down ? 'down' : 'up';
+    const effectiveSteps = steps ?? (direction === 'down' ? 1 : undefined);
+
+    const res = migrateThsSchema(schema, { direction, steps: effectiveSteps });
+    const migrated = res.schema;
+
+    // Ensure the migrated schema still validates and lints cleanly.
+    const lintIssues = lintThs(migrated);
+    const errors = lintIssues.filter((i) => i.severity === 'error');
+    if (errors.length > 0) {
+      console.error(formatIssues(lintIssues));
+      process.exitCode = 1;
+      return;
+    }
+
+    const outJson = JSON.stringify(migrated, null, 2);
+    if (opts.inPlace) {
+      fs.writeFileSync(schemaPath, outJson);
+    } else if (opts.out) {
+      ensureDir(path.dirname(opts.out));
+      fs.writeFileSync(opts.out, outJson);
+    } else {
+      console.log(outJson);
+    }
+
+    const appliedMsg = res.appliedNow.length > 0 ? res.appliedNow.join(', ') : '(none)';
+    console.error(`migrations (${direction}) applied: ${appliedMsg}`);
   });
 
 program

packages/schema/src/index.ts

@@ -5,3 +5,5 @@ export { computeSchemaHash } from './hash.js';
 export { importLegacyContractsJson } from './importLegacy.js';
 export { lintThs } from './lint.js';
 export { validateThsStructural } from './validate.js';
+export type { ThsMigration } from './migrations/types.js';
+export { listThsMigrations, migrateThsSchema } from './migrations/index.js';

packages/schema/src/migrations/001-normalize-features.ts

@@ -0,0 +1,51 @@
+import type { ThsSchema } from '../types.js';
+import type { ThsMigration } from './types.js';
+
+const DEFAULTS = {
+  indexer: false,
+  delegation: false,
+  uploads: false,
+  onChainIndexing: true
+} as const;
+
+function clone<T>(v: T): T {
+  return JSON.parse(JSON.stringify(v));
+}
+
+export const migration001NormalizeFeatures: ThsMigration = {
+  id: '001-normalize-features',
+  description: 'Make implicit app.features defaults explicit (reversible).',
+  up: (schema: ThsSchema): ThsSchema => {
+    const out = clone(schema);
+    out.app = out.app ?? ({} as any);
+    const features = ((out.app as any).features ?? {}) as Record<string, unknown>;
+
+    for (const [k, v] of Object.entries(DEFAULTS)) {
+      if (!(k in features)) features[k] = v;
+    }
+
+    (out.app as any).features = features;
+    return out;
+  },
+  down: (schema: ThsSchema): ThsSchema => {
+    const out = clone(schema);
+    const features = (out.app as any)?.features;
+    if (!features || typeof features !== 'object') return out;
+
+    // Remove explicit defaults.
+    for (const [k, v] of Object.entries(DEFAULTS)) {
+      if ((features as any)[k] === v) delete (features as any)[k];
+    }
+
+    if (Object.keys(features as any).length === 0) {
+      delete (out.app as any).features;
+    } else {
+      (out.app as any).features = features;
+    }
+
+    return out;
+  }
+};
+
+export default migration001NormalizeFeatures;
+

packages/schema/src/migrations/index.ts

@@ -0,0 +1,69 @@
+import type { ThsSchema } from '../types.js';
+import type { ThsMigration } from './types.js';
+
+import migration001 from './001-normalize-features.js';
+
+export const THS_MIGRATIONS: ThsMigration[] = [migration001];
+
+function clone<T>(v: T): T {
+  return JSON.parse(JSON.stringify(v));
+}
+
+function readApplied(schema: any): string[] {
+  const ids = schema?.metadata?.tokenhost?.appliedMigrations;
+  return Array.isArray(ids) ? ids.filter((x) => typeof x === 'string') : [];
+}
+
+function writeApplied(schema: any, ids: string[]) {
+  schema.metadata = schema.metadata ?? {};
+  schema.metadata.tokenhost = schema.metadata.tokenhost ?? {};
+  schema.metadata.tokenhost.appliedMigrations = ids;
+}
+
+export function listThsMigrations(): ThsMigration[] {
+  return [...THS_MIGRATIONS];
+}
+
+export function migrateThsSchema(
+  schema: ThsSchema,
+  opts?: { direction?: 'up' | 'down'; steps?: number }
+): { schema: ThsSchema; appliedNow: string[]; appliedTotal: string[] } {
+  const direction = opts?.direction ?? 'up';
+  const maxSteps = typeof opts?.steps === 'number' && Number.isFinite(opts.steps) ? Math.max(0, Math.floor(opts.steps)) : Number.POSITIVE_INFINITY;
+
+  let out = clone(schema);
+  const applied = readApplied(out);
+  const appliedSet = new Set(applied);
+  const appliedNow: string[] = [];
+
+  if (direction === 'up') {
+    let steps = 0;
+    for (const m of THS_MIGRATIONS) {
+      if (appliedSet.has(m.id)) continue;
+      if (steps >= maxSteps) break;
+      out = m.up(out);
+      applied.push(m.id);
+      appliedSet.add(m.id);
+      appliedNow.push(m.id);
+      steps++;
+    }
+  } else {
+    // Down: revert from the end of the applied list.
+    let steps = 0;
+    while (steps < maxSteps && applied.length > 0) {
+      const lastId = applied[applied.length - 1]!;
+      const m = THS_MIGRATIONS.find((x) => x.id === lastId);
+      if (!m) {
+        throw new Error(`Cannot down-migrate unknown migration id: ${lastId}`);
+      }
+      out = m.down(out);
+      applied.pop();
+      appliedSet.delete(lastId);
+      appliedNow.push(lastId);
+      steps++;
+    }
+  }
+
+  writeApplied(out, applied);
+  return { schema: out, appliedNow, appliedTotal: applied };
+}

packages/schema/src/migrations/types.ts

@@ -0,0 +1,9 @@
+import type { ThsSchema } from '../types.js';
+
+export type ThsMigration = {
+  id: string;
+  description: string;
+  up: (schema: ThsSchema) => ThsSchema;
+  down: (schema: ThsSchema) => ThsSchema;
+};
+

test/testMigrations.js

@@ -0,0 +1,53 @@
+import { expect } from 'chai';
+
+import { migrateThsSchema, validateThsStructural } from '@tokenhost/schema';
+
+function minimalSchema(overrides = {}) {
+  return {
+    thsVersion: '2025-12',
+    schemaVersion: '0.0.1',
+    app: { name: 'Test App', slug: 'test-app' },
+    collections: [
+      {
+        name: 'Item',
+        fields: [{ name: 'title', type: 'string', required: true }],
+        createRules: { required: ['title'], access: 'public' },
+        visibilityRules: { gets: ['title'], access: 'public' },
+        updateRules: { mutable: ['title'], access: 'owner' },
+        deleteRules: { softDelete: true, access: 'owner' },
+        indexes: { unique: [], index: [] }
+      }
+    ],
+    ...overrides
+  };
+}
+
+describe('THS schema migrations', function () {
+  it('up migration makes app.features defaults explicit', function () {
+    const input = minimalSchema();
+    const structural = validateThsStructural(input);
+    expect(structural.ok).to.equal(true);
+
+    const res = migrateThsSchema(structural.data, { direction: 'up' });
+    expect(res.appliedNow).to.include('001-normalize-features');
+
+    expect(res.schema.app).to.have.property('features');
+    expect(res.schema.app.features).to.deep.include({
+      indexer: false,
+      delegation: false,
+      uploads: false,
+      onChainIndexing: true
+    });
+  });
+
+  it('down migration reverts explicit defaults', function () {
+    const input = minimalSchema();
+    const up = migrateThsSchema(input, { direction: 'up' });
+    const down = migrateThsSchema(up.schema, { direction: 'down', steps: 1 });
+
+    // Features become optional again after down.
+    expect((down.schema.app || {}).features).to.equal(undefined);
+    expect((down.schema.metadata || {}).tokenhost?.appliedMigrations || []).to.deep.equal([]);
+  });
+});
+