spine-framework 0.2.1 → 0.2.2

package/.framework/cli/commands/update-app.ts

@@ -0,0 +1,397 @@
+/// <reference types="node" />
+/**
+ * @module cli/commands/update-app
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine-framework update-app <slug>` — Check for and assist with app updates.
+ *
+ * Design principle: the agentic IDE is the merge tool. This command never
+ * writes to custom/apps/. It only:
+ *   1. Gets the new version into node_modules/ (read-only upstream reference)
+ *   2. Gives the agent a complete picture: versions, changelog, file diff summary
+ *   3. Records the new version in DB once the agent signals it is done (--accept)
+ *
+ * **Usage:**
+ * ```bash
+ * spine-framework update-app cortex              # check for updates
+ * spine-framework update-app cortex --dry-run    # full plan: changelog + file diff
+ * spine-framework update-app cortex --accept     # record new version in DB only
+ * ```
+ */
+
+import type { Command } from 'commander'
+import { existsSync, readFileSync, readdirSync, createReadStream } from 'fs'
+import { resolve, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { execSync } from 'child_process'
+import { adminDb } from '../../functions/_shared/index.ts'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const PROJECT_ROOT = process.cwd()
+
+interface UpdateOptions {
+  dryRun: boolean
+  accept: boolean
+}
+
+interface InstallationRecord {
+  app_slug: string
+  is_enabled: boolean
+  installed_version: string | null
+  package_name: string | null
+}
+
+// ─── NPM REGISTRY ─────────────────────────────────────────────────────────────
+
+async function fetchLatestVersion(packageName: string): Promise<string | null> {
+  try {
+    const url = `https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`
+    const res = await fetch(url)
+    if (!res.ok) return null
+    const data = await res.json() as { version?: string }
+    return data.version || null
+  } catch {
+    return null
+  }
+}
+
+// ─── SEMVER COMPARISON ────────────────────────────────────────────────────────
+
+function parseSemver(v: string): [number, number, number] {
+  const parts = v.replace(/^v/, '').split('.').map(Number)
+  return [parts[0] || 0, parts[1] || 0, parts[2] || 0]
+}
+
+function isNewer(candidate: string, current: string): boolean {
+  const [cMaj, cMin, cPatch] = parseSemver(candidate)
+  const [iMaj, iMin, iPatch] = parseSemver(current)
+  if (cMaj !== iMaj) return cMaj > iMaj
+  if (cMin !== iMin) return cMin > iMin
+  return cPatch > iPatch
+}
+
+function changelogBetween(
+  changelog: Array<{ version: string; notes: string[] }>,
+  fromVersion: string,
+  toVersion: string,
+): Array<{ version: string; notes: string[] }> {
+  return changelog.filter(entry => isNewer(entry.version, fromVersion) && !isNewer(entry.version, toVersion))
+}
+
+// ─── FILE DIFF SUMMARY ────────────────────────────────────────────────────────
+
+function readFileSafe(filePath: string): string | null {
+  try { return readFileSync(filePath, 'utf8') } catch { return null }
+}
+
+function diffAppFiles(
+  pkgDir: string,
+  localDir: string,
+  dirs: string[],
+  topFiles: string[],
+): { changed: string[]; added: string[]; localOnly: string[] } {
+  const changed: string[] = []
+  const added: string[] = []
+  const localOnly: string[] = []
+
+  function diffFile(relPath: string) {
+    const upstreamContent = readFileSafe(resolve(pkgDir, relPath))
+    const localContent = readFileSafe(resolve(localDir, relPath))
+    if (upstreamContent === null && localContent !== null) {
+      localOnly.push(relPath)
+    } else if (upstreamContent !== null && localContent === null) {
+      added.push(relPath)
+    } else if (upstreamContent !== null && localContent !== null && upstreamContent !== localContent) {
+      changed.push(relPath)
+    }
+  }
+
+  for (const file of topFiles) {
+    diffFile(file)
+  }
+
+  for (const dir of dirs) {
+    const upstreamDirPath = resolve(pkgDir, dir)
+    if (!existsSync(upstreamDirPath)) continue
+    const walkDir = (base: string, rel: string) => {
+      const entries = readdirSync(resolve(base, rel), { withFileTypes: true })
+      for (const entry of entries) {
+        const entryRel = rel ? `${rel}/${entry.name}` : entry.name
+        if (entry.isDirectory()) {
+          walkDir(base, entryRel)
+        } else {
+          diffFile(`${dir}/${entryRel}`)
+        }
+      }
+    }
+    walkDir(upstreamDirPath, '')
+  }
+
+  return { changed, added, localOnly }
+}
+
+// ─── SEED HELPERS (reused from install-app logic) ─────────────────────────────
+
+async function resolveAppId(slug: string): Promise<string | null> {
+  const { data } = await adminDb.from('apps').select('id').eq('slug', slug).single()
+  return data?.id || null
+}
+
+async function upsertSeedFile(
+  appId: string,
+  seedFile: string,
+  records: any[],
+): Promise<void> {
+  const tableMap: Record<string, string> = {
+    'types.json': 'types',
+    'link-types.json': 'link_types',
+    'roles.json': 'roles',
+    'pipelines.json': 'pipelines',
+  }
+  const table = tableMap[seedFile]
+  if (!table) return
+
+  const conflictMap: Record<string, string> = {
+    types: 'app_id,kind,slug',
+    link_types: 'app_id,slug',
+    roles: 'app_id,slug',
+    pipelines: 'app_id,name',
+  }
+
+  for (const record of records) {
+    await adminDb.from(table).upsert(
+      { ...record, app_id: appId },
+      { onConflict: conflictMap[table], ignoreDuplicates: false },
+    )
+  }
+}
+
+async function reapplySeed(slug: string, pkgDir: string): Promise<void> {
+  const appId = await resolveAppId(slug)
+  if (!appId) {
+    console.log(`  ⚠️  App '${slug}' not found in DB — skipping seed re-apply`)
+    return
+  }
+
+  const seedDir = resolve(pkgDir, 'seed')
+  if (!existsSync(seedDir)) return
+
+  const SEED_ORDER = ['accounts.json', 'types.json', 'link-types.json', 'roles.json', 'pipelines.json', 'triggers.json']
+  const allFiles = readdirSync(seedDir).filter(f => f.endsWith('.json'))
+  const seedFiles = [
+    ...SEED_ORDER.filter(f => allFiles.includes(f)),
+    ...allFiles.filter(f => !SEED_ORDER.includes(f)),
+  ]
+
+  for (const file of seedFiles) {
+    try {
+      const records = JSON.parse(readFileSync(resolve(seedDir, file), 'utf8'))
+      if (Array.isArray(records)) {
+        await upsertSeedFile(appId, file, records)
+        console.log(`  ✓ Re-seeded ${file}`)
+      }
+    } catch { /* ignore parse errors */ }
+  }
+}
+
+// ─── MAIN ─────────────────────────────────────────────────────────────────────
+
+async function updateApp(slug: string, options: UpdateOptions): Promise<void> {
+  console.log(`\n🔄 Update check for '${slug}'...\n`)
+
+  // 1. Read installation record from DB
+  const { data: installation, error: dbErr } = await adminDb
+    .from('app_installations')
+    .select('app_slug, is_enabled, installed_version, package_name')
+    .eq('app_slug', slug)
+    .maybeSingle() as { data: InstallationRecord | null; error: any }
+
+  if (dbErr) {
+    console.error(`  ❌ DB error: ${dbErr.message}`)
+    console.error(`     Has migration 004_app_version_tracking.sql been applied?`)
+    process.exit(1)
+  }
+
+  if (!installation) {
+    console.error(`  ❌ App '${slug}' is not installed (not found in app_installations).`)
+    console.error(`     Run: spine-framework install-app spine-framework-${slug}`)
+    process.exit(1)
+  }
+
+  const packageName = installation.package_name || `spine-framework-${slug}`
+  const installedVersion = installation.installed_version
+
+  if (!installedVersion) {
+    console.log(`  ⚠️  No installed_version recorded. Re-install to track version:`)
+    console.log(`     spine-framework install-app ${packageName} --force`)
+    process.exit(1)
+  }
+
+  // 2. Fetch latest from npm registry
+  process.stdout.write(`  Checking npm registry for ${packageName}... `)
+  const latestVersion = await fetchLatestVersion(packageName)
+  if (!latestVersion) {
+    console.log(`❌`)
+    console.error(`  Could not reach npm registry. Check your internet connection.`)
+    process.exit(1)
+  }
+  console.log(`done`)
+
+  console.log(`  Installed : v${installedVersion}`)
+  console.log(`  Latest    : v${latestVersion}`)
+
+  if (!isNewer(latestVersion, installedVersion)) {
+    console.log(`\n✅ Already up to date.\n`)
+    return
+  }
+
+  console.log(`  Status    : update available\n`)
+
+  if (!options.dryRun && !options.accept) {
+    console.log(`  Run with --dry-run to see changelog and file diff.`)
+    console.log(`  Run with --accept after merging to record the new version.\n`)
+    return
+  }
+
+  // ── --dry-run ──────────────────────────────────────────────────────────────
+  if (options.dryRun) {
+    console.log(`📥 Fetching ${packageName}@latest into node_modules (read-only reference)...`)
+    try {
+      execSync(`npm install ${packageName}@latest`, { cwd: PROJECT_ROOT, stdio: 'inherit' })
+      console.log(`  ✓ Done\n`)
+    } catch (err: any) {
+      console.error(`  ❌ npm install failed: ${err.message}`)
+      process.exit(1)
+    }
+
+    const pkgDir = resolve(PROJECT_ROOT, `node_modules/${packageName}`)
+    const localDir = resolve(PROJECT_ROOT, `custom/apps/${slug}`)
+
+    // Read changelog from new upstream version
+    const upstreamManifestPath = resolve(pkgDir, 'manifest.json')
+    let changelog: Array<{ version: string; notes: string[] }> = []
+    let newVersion = latestVersion
+    if (existsSync(upstreamManifestPath)) {
+      try {
+        const m = JSON.parse(readFileSync(upstreamManifestPath, 'utf8'))
+        changelog = m.changelog || []
+        newVersion = m.version || latestVersion
+      } catch { /* ignore */ }
+    }
+
+    // Print changelog entries between installed and latest
+    const relevantChangelog = changelogBetween(changelog, installedVersion, newVersion)
+    console.log(`📋 Changelog (v${installedVersion} → v${newVersion}):`)
+    if (relevantChangelog.length === 0) {
+      console.log(`  (no changelog entries found between these versions)`)
+    } else {
+      for (const entry of relevantChangelog) {
+        console.log(`\n  v${entry.version}:`)
+        for (const note of entry.notes) {
+          console.log(`    • ${note}`)
+        }
+      }
+    }
+
+    // Read directories list from upstream manifest
+    let appDirs = ['pages', 'components', 'hooks', 'config', 'seed', 'api', 'functions', 'lib']
+    try {
+      const m = JSON.parse(readFileSync(upstreamManifestPath, 'utf8'))
+      if (Array.isArray(m.directories)) appDirs = m.directories.filter((d: string) => d !== 'migrations' && d !== 'tests')
+    } catch { /* use defaults */ }
+
+    const topFiles = ['index.tsx', 'manifest.json']
+    const diff = diffAppFiles(pkgDir, localDir, appDirs, topFiles)
+
+    console.log(`\n📁 File diff summary (upstream vs your version):`)
+    console.log(`   Upstream (new) : node_modules/${packageName}/`)
+    console.log(`   Your version   : custom/apps/${slug}/\n`)
+
+    if (diff.changed.length === 0 && diff.added.length === 0 && diff.localOnly.length === 0) {
+      console.log(`  (no file differences detected)`)
+    } else {
+      if (diff.changed.length > 0) {
+        console.log(`  Modified (${diff.changed.length}) — review and merge:`)
+        diff.changed.forEach(f => console.log(`    ~ ${f}`))
+      }
+      if (diff.added.length > 0) {
+        console.log(`\n  New in upstream (${diff.added.length}) — copy to your version:`)
+        diff.added.forEach(f => console.log(`    + ${f}`))
+      }
+      if (diff.localOnly.length > 0) {
+        console.log(`\n  Only in your version (${diff.localOnly.length}) — your additions, keep them:`)
+        diff.localOnly.forEach(f => console.log(`    → ${f}`))
+      }
+    }
+
+    console.log(`\n──────────────────────────────────────────────────────────────`)
+    console.log(`  Next steps:`)
+    console.log(`    1. Review and merge changed files listed above`)
+    console.log(`    2. Run: spine-framework update-app ${slug} --accept`)
+    console.log(`──────────────────────────────────────────────────────────────\n`)
+    return
+  }
+
+  // ── --accept ──────────────────────────────────────────────────────────────
+  if (options.accept) {
+    console.log(`📝 Recording update...`)
+
+    const pkgDir = resolve(PROJECT_ROOT, `node_modules/${packageName}`)
+    if (!existsSync(pkgDir)) {
+      console.error(`  ❌ ${packageName} not found in node_modules.`)
+      console.error(`     Run --dry-run first to fetch the new version.`)
+      process.exit(1)
+    }
+
+    // Read new version from upstream manifest
+    let newVersion = latestVersion
+    const upstreamManifestPath = resolve(pkgDir, 'manifest.json')
+    if (existsSync(upstreamManifestPath)) {
+      try {
+        newVersion = JSON.parse(readFileSync(upstreamManifestPath, 'utf8')).version || latestVersion
+      } catch { /* use latestVersion */ }
+    }
+
+    const { error: updateErr } = await adminDb
+      .from('app_installations')
+      .update({
+        installed_version: newVersion,
+        updated_at: new Date().toISOString(),
+      })
+      .eq('app_slug', slug)
+
+    if (updateErr) {
+      console.error(`  ❌ Failed to update installed_version: ${updateErr.message}`)
+      process.exit(1)
+    }
+
+    console.log(`  ✓ installed_version updated to v${newVersion}`)
+
+    // Re-apply seed (idempotent)
+    console.log(`\n🌱 Re-applying seed data (idempotent)...`)
+    await reapplySeed(slug, pkgDir)
+
+    console.log(`\n✅ Update recorded for '${slug}' → v${newVersion}`)
+    console.log(`   Run 'spine-framework status' to verify.\n`)
+  }
+}
+
+export function registerUpdateAppCommands(program: Command) {
+  program
+    .command('update-app <slug>')
+    .description('Check for app updates and assist with agentic-IDE-driven merge')
+    .option('--dry-run', 'Fetch latest, show changelog + file diff (no writes to custom/apps/)', false)
+    .option('--accept', 'Record new version in DB after agent has merged files', false)
+    .action(async (slug, opts) => {
+      try {
+        await updateApp(slug, opts)
+      } catch (err: any) {
+        console.error('Error:', err.message)
+        if (process.env.SPINE_CLI_DEBUG) console.error(err.stack)
+        process.exit(1)
+      }
+    })
+}

package/.framework/cli/index.ts

@@ -21,7 +21,10 @@
  * | migrations  | commands/migrations.ts     |
  * | init        | commands/init.ts           |
  * | install-app | commands/install-app.ts    |
+ * | update-app  | commands/update-app.ts     |
+ * | publish     | commands/publish.ts        |
  * | status      | commands/status.ts         |
+ * | claim       | commands/claim.ts          |
  * | uninstall   | commands/uninstall-app.ts  |
  *
  * **Usage:**
@@ -75,7 +78,10 @@ if (!noDbCommands.includes(subcommand)) {
     { registerGenerateCommands },
     { registerCreateAppCommands },
     { registerInstallAppCommands },
+    { registerUpdateAppCommands },
+    { registerPublishCommands },
     { registerStatusCommands },
+    { registerClaimCommands },
     { registerUninstallAppCommands },
   ] = await Promise.all([
     import('./commands/auth.ts'),
@@ -90,7 +96,10 @@ if (!noDbCommands.includes(subcommand)) {
     import('./commands/generate.ts'),
     import('./commands/create-app.ts'),
     import('./commands/install-app.ts'),
+    import('./commands/update-app.ts'),
+    import('./commands/publish.ts'),
     import('./commands/status.ts'),
+    import('./commands/claim.ts'),
     import('./commands/uninstall-app.ts'),
   ])
 
@@ -106,7 +115,10 @@ if (!noDbCommands.includes(subcommand)) {
   registerGenerateCommands(program)
   registerCreateAppCommands(program)
   registerInstallAppCommands(program)
+  registerUpdateAppCommands(program)
+  registerPublishCommands(program)
   registerStatusCommands(program)
+  registerClaimCommands(program)
   registerUninstallAppCommands(program)
 }
 

package/.framework/migrations/000_foundation.sql

@@ -139,8 +139,7 @@ CREATE TABLE IF NOT EXISTS public.roles (
   app_id       uuid,
   account_id   uuid,
   created_at   timestamptz DEFAULT now(),
-  updated_at   timestamptz DEFAULT now(),
-  UNIQUE (app_id, slug)
+  updated_at   timestamptz DEFAULT now()
 );
 
 -- apps (no dependencies on other custom tables)
@@ -764,8 +763,7 @@ CREATE TABLE IF NOT EXISTS public.app_installations (
   app_slug     varchar NOT NULL,
   is_enabled   boolean DEFAULT true,
   installed_at timestamptz DEFAULT now(),
-  updated_at   timestamptz DEFAULT now(),
-  UNIQUE (account_id, app_slug)
+  updated_at   timestamptz DEFAULT now()
 );
 
 -- ---------------------------------------------------------------------------
@@ -795,6 +793,14 @@ CREATE INDEX IF NOT EXISTS idx_api_keys_key_value   ON public.api_keys (key_valu
 
 CREATE INDEX IF NOT EXISTS idx_app_installations_account ON public.app_installations (account_id) WHERE (is_enabled = true);
 CREATE INDEX IF NOT EXISTS idx_app_installations_slug    ON public.app_installations (app_slug) WHERE (is_enabled = true);
+-- Dedup: system installs (account_id IS NULL) — one row per app slug
+CREATE UNIQUE INDEX IF NOT EXISTS idx_app_installations_slug_no_account
+  ON public.app_installations (app_slug)
+  WHERE account_id IS NULL;
+-- Dedup: tenant installs (account_id IS NOT NULL) — one row per (slug, account)
+CREATE UNIQUE INDEX IF NOT EXISTS idx_app_installations_slug_with_account
+  ON public.app_installations (app_slug, account_id)
+  WHERE account_id IS NOT NULL;
 
 CREATE INDEX IF NOT EXISTS idx_apps_owner       ON public.apps (owner_account_id);
 CREATE INDEX IF NOT EXISTS idx_apps_slug        ON public.apps (slug);
@@ -848,6 +854,14 @@ CREATE INDEX IF NOT EXISTS idx_prompt_configs_app     ON public.prompt_configs (
 CREATE INDEX IF NOT EXISTS idx_prompt_configs_slug    ON public.prompt_configs (slug);
 
 CREATE INDEX IF NOT EXISTS idx_roles_slug ON public.roles (slug);
+-- Dedup: system roles (app_id IS NULL) — one row per slug globally
+CREATE UNIQUE INDEX IF NOT EXISTS idx_roles_slug_no_app
+  ON public.roles (slug)
+  WHERE app_id IS NULL;
+-- Dedup: app-scoped roles (app_id IS NOT NULL) — one row per (app_id, slug)
+CREATE UNIQUE INDEX IF NOT EXISTS idx_roles_slug_with_app
+  ON public.roles (app_id, slug)
+  WHERE app_id IS NOT NULL;
 
 CREATE INDEX IF NOT EXISTS idx_se_account  ON public.schedule_executions (account_id);
 CREATE INDEX IF NOT EXISTS idx_se_schedule ON public.schedule_executions (schedule_id);

package/.framework/migrations/004_app_version_tracking.sql

@@ -0,0 +1,8 @@
+-- 004_app_version_tracking.sql
+-- Adds version tracking columns to app_installations so the CLI and
+-- agentic IDE can detect drift between the installed version and the
+-- latest published npm package version.
+
+ALTER TABLE public.app_installations
+  ADD COLUMN IF NOT EXISTS installed_version varchar,
+  ADD COLUMN IF NOT EXISTS package_name      varchar;

package/.framework/src/App.tsx

@@ -8,7 +8,7 @@ import { NotFoundPage } from './pages/NotFoundPage'
 import { DashboardPage } from './pages/DashboardPage'
 import { AppWrapper } from './components/AppWrapper'
 import { AppsRegistryProvider, useAppsRegistry } from './contexts/AppContext'
-import { CustomAppLoader } from './components/CustomAppLoader'
+import { CustomAppLoader, getInstalledAppSlugs } from './components/CustomAppLoader'
 import { GenericAppShell } from './components/app-shell/GenericAppShell'
 import { APIPage } from './pages/spine-framework/APIPage'
 import { CLIPage } from './pages/spine-framework/CLIPage'
@@ -58,9 +58,14 @@ function AuthenticatedRouter() {
     )
   }
 
+  // Filter to apps that are physically present in this build (custom renderer only —
+  // generic apps have no module to load so they're always allowed through).
+  const installedSlugs = getInstalledAppSlugs()
+
   // Sort: explicit prefixes first, root (/) last
   const sorted = [...apps]
     .filter(app => app.slug !== 'spine-framework' && !app.route_prefix?.startsWith('/spine-framework'))
+    .filter(app => app.renderer !== 'custom' || installedSlugs.has(app.slug))
     .sort((a, b) => {
       if (a.route_prefix === '/') return 1
       if (b.route_prefix === '/') return -1

package/.framework/src/components/CustomAppLoader.tsx

@@ -60,6 +60,23 @@ class AppErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState>
 const customAppModules = import.meta.glob('../../custom/apps/*/index.tsx')
 const coreAppModules   = import.meta.glob('../apps/*/index.tsx')
 
+// Extract app slug from glob key path (e.g., '.../apps/xyz/index.tsx' → 'xyz')
+function slugFromKey(key: string): string {
+  return key.split('/').slice(-2)[0]
+}
+
+/**
+ * Returns the set of app slugs that are physically present in this build.
+ * Used by App.tsx to filter DB app records down to only what's actually installed,
+ * preventing route registration for apps that exist in the DB but not this deployment.
+ */
+export function getInstalledAppSlugs(): Set<string> {
+  const slugs = new Set<string>()
+  Object.keys(customAppModules).forEach(k => slugs.add(slugFromKey(k)))
+  Object.keys(coreAppModules).forEach(k => slugs.add(slugFromKey(k)))
+  return slugs
+}
+
 // Module-level cache for lazy components to avoid re-creating on each render
 const appModuleCache = new Map<string, React.LazyExoticComponent<React.ComponentType>>()
 

package/bin/{spine-framework.cjs → spine-framework.js}

@@ -10,7 +10,7 @@ const projectRoot = resolve(pkgRoot, '../..')
 
 // Handle no-args case here — before spawning tsx or loading db.ts
 if (process.argv.length === 2) {
-  require(resolve(__dirname, 'welcome.cjs'))
+  require(resolve(__dirname, 'welcome.js'))
   process.exit(0)
 }
 

package/bin/{welcome.cjs → welcome.js}

@@ -12,7 +12,7 @@ const lines = [
   '│   ███████╗██████╔╝██║██╔██╗ ██║█████╗                      │',
   '│   ╚════██║██╔═══╝ ██║██║╚██╗██║██╔══╝                      │',
   '│   ███████║██║     ██║██║ ╚████║███████╗                    │',
-  '│   ╚══════╝╚═╝     ╚═╝╚═╝  ╚═══╝╚══════╝  Framework v0.1   │',
+  '│   ╚══════╝╚═╝     ╚═╝╚═╝  ╚═══╝╚══════╝  Framework v0.2   │',
   '│                                                              │',
   '╰──────────────────────────────────────────────────────────────╯',
   '',
@@ -38,7 +38,7 @@ const lines = [
   '    spine-framework install-app <app-slug>   # optional apps',
   '    npm run assemble && netlify dev           # start dev server',
   '',
-  '  Docs: https://github.com/art-mojo-admin/spine',
+  '  Docs: https://github.com/spine-framework/spine-framework',
   '',
 ]
 

package/dist/cli/commands/claim.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @module cli/commands/claim
+ * @audience installer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine-framework claim` — Claim framework installation via Spine Portal.
+ *
+ * Engagement-based claim system that offers contextual prompts based on
+ * user activity. Tracks engagement signals and triggers claim prompts
+ * at value-realization moments.
+ *
+ * **Usage:**
+ * ```bash
+ * spine-framework claim              # Interactive claim flow
+ * spine-framework claim --status     # Show claim status only
+ * spine-framework claim --token <t>  # Headless claim with token
+ * ```
+ */
+import type { Command } from 'commander';
+import { type EngagementData, type ClaimPrompt, type EngagementSignalType } from '../../config/signals.ts';
+export interface SerialData {
+    serial_number: string;
+    salt: string;
+    created_at: string;
+    framework_version: string;
+    account_id: string | null;
+    machine_fingerprint: string;
+}
+export declare function ensureSerialData(): SerialData;
+export declare function readEngagementData(): EngagementData | null;
+export declare function writeEngagementData(data: EngagementData): void;
+export declare function recordEngagementSignal(signalType: EngagementSignalType): void;
+export declare function shouldOfferClaim(): ClaimPrompt | null;
+export interface FrameworkInstallSignal {
+    signal_type: 'framework_install';
+    install_serial: string;
+    package: string;
+    version: string;
+    anonymous_id: string;
+    machine_fingerprint: string;
+    platform: string;
+    timestamp: string;
+}
+export interface AppInstallSignal {
+    signal_type: 'app_install';
+    package: string;
+    version: string;
+    framework_install_serial: string;
+    app_serial: string;
+    timestamp: string;
+}
+export declare function sendFrameworkInstallSignal(): Promise<void>;
+export declare function sendAppInstallSignal(packageName: string, version: string): Promise<void>;
+export declare function registerClaimCommands(program: Command): void;
+//# sourceMappingURL=claim.d.ts.map

package/dist/cli/commands/claim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim.d.ts","sourceRoot":"","sources":["../../../.framework/cli/commands/claim.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAKxC,OAAO,EAAkD,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAA;AAS1J,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,iBAAiB,EAAE,MAAM,CAAA;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,mBAAmB,EAAE,MAAM,CAAA;CAC5B;AAiBD,wBAAgB,gBAAgB,IAAI,UAAU,CA6B7C;AAeD,wBAAgB,kBAAkB,IAAI,cAAc,GAAG,IAAI,CAO1D;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI,CAK9D;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,oBAAoB,GAAG,IAAI,CAgC7E;AAED,wBAAgB,gBAAgB,IAAI,WAAW,GAAG,IAAI,CA8BrD;AAID,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,mBAAmB,CAAA;IAChC,cAAc,EAAE,MAAM,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;IACpB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,aAAa,CAAA;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,wBAAwB,EAAE,MAAM,CAAA;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC,CAuBhE;AAED,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB9F;AAkLD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAe5D"}

package/dist/cli/commands/install-app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install-app.d.ts","sourceRoot":"","sources":["../../../.framework/cli/commands/install-app.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAugBxC,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,QAgB1D"}
+{"version":3,"file":"install-app.d.ts","sourceRoot":"","sources":["../../../.framework/cli/commands/install-app.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAmkBxC,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,QAgB1D"}

package/dist/cli/commands/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../../.framework/cli/commands/migrate.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAuGxC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,QAevD"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../../.framework/cli/commands/migrate.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAmHxC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,QAevD"}

package/dist/cli/commands/publish.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @module cli/commands/publish
+ * @audience developer
+ * @layer cli
+ * @stability stable
+ *
+ * `spine-framework publish` — Bump version, write changelog, publish to npm, commit.
+ *
+ * Run from the spine-ia coding repo. Handles both the framework package and
+ * individual app packages (cortex, portal, etc.).
+ *
+ * **Usage:**
+ * ```bash
+ * spine-framework publish                          # publish framework (patch bump)
+ * spine-framework publish --app cortex             # publish cortex app (patch bump)
+ * spine-framework publish --app cortex --bump minor
+ * spine-framework publish --app cortex --bump patch --notes "Fix sidebar nav"
+ * spine-framework publish --app cortex --ci --notes "Fix sidebar nav" --bump patch
+ * ```
+ */
+import type { Command } from 'commander';
+export declare function registerPublishCommands(program: Command): void;
+//# sourceMappingURL=publish.d.ts.map

package/dist/cli/commands/publish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../../../.framework/cli/commands/publish.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAsJxC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,QAkBvD"}