@notis_ai/cli 0.2.0-beta.19.1 → 0.2.0-beta.196.1

package/src/runtime/skill-sync/types.ts

@@ -0,0 +1,157 @@
+export interface AgentTargets {
+  notis: boolean;
+  claude_code: boolean;
+  cursor: boolean;
+  codex: boolean;
+}
+
+export interface NativeSkillReference {
+  kind: 'native_standalone_skill';
+  skill_id: string;
+  access_revision: number;
+  version: { revision: number; digest: string };
+}
+
+export interface SyncedSkill {
+  cloudId: string;
+  nativeReference?: NativeSkillReference;
+  nativeDisplayName?: string;
+  nativeScope?: string;
+  nativeSettingsRevision?: number;
+  /** Retain managed provenance even when its cloud access is removed. */
+  nativeUnavailable?: boolean;
+  folderHash: string;
+  agentTargets: AgentTargets;
+  /** Actual readable managed links, never inferred from desired targets. */
+  verifiedAgentLinks?: Partial<AgentTargets>;
+  cloudUpdatedAt?: string;
+  /** Content accepted on disk; independent of server-specific folder hash formats. */
+  cloudContentHash?: string;
+  /** Relative paths the last successful write put in this folder. Anything else in
+   * the folder was created locally (a running skill's output) and survives the next
+   * cloud write; anything listed here that the cloud later drops is deleted. */
+  appliedFiles?: string[];
+  /** `skill_folder_hash` of the cloud revision a successful write actually applied.
+   * The server may compute that hash with a different construction than the local
+   * folder hash (bundle-entry hashes do), so only cloud-to-cloud comparison tells
+   * "the cloud moved" apart from "the two sides hash differently". */
+  appliedCloudFolderHash?: string;
+  syncedAt: string;
+}
+
+export interface NotisSyncState {
+  version: 1;
+  lastSyncedAt: string | null;
+  skills: Record<string, SyncedSkill>;
+  /** Historical folder aliases are provenance, never authority or write pins. */
+  nativeHistory?: Record<string, { names: string[] }>;
+}
+
+/** A successful write, plus the paths it put on disk so the next one can tell
+ * cloud-managed files apart from whatever ran inside the folder since. */
+export interface SkillWriteOutcome {
+  written: true;
+  appliedFiles: string[];
+}
+
+export interface LocalSkill {
+  name: string;
+  skillMd: string;
+  description: string;
+  folderHash: string;
+  directoryPath: string;
+  sourceUrl?: string;
+  bundleFiles?: BundleFile[];
+  cloudId?: string;
+  nativeReference?: NativeSkillReference;
+  displayName?: string;
+  nativeScope?: string;
+  nativeFilesCurrent?: boolean;
+  nativeBaseFolderHash?: string;
+}
+
+export interface BundleFile {
+  path: string;
+  content_b64: string;
+}
+
+export interface CloudSkill {
+  updated_at?: string;
+  id: string;
+  name: string;
+  description: string | null;
+  skill_md: string | null;
+  agent_targets?: Partial<AgentTargets> | null;
+  skill_folder_hash?: string | null;
+  skill_source_url?: string | null;
+  bundle_files?: BundleFile[] | null;
+  bundle_hydration_failed?: boolean | null;
+  source: string;
+  status: string;
+  native_reference?: NativeSkillReference;
+  display_name?: string;
+  native_scope?: string;
+  native_settings?: { revision: number; enabled: boolean; agent_targets: AgentTargets; updated_at: string };
+}
+
+export interface SyncSettings {
+  skill_sync_protocol?: number;
+  sync_scope?: string;
+  sync_namespace?: string | null;
+  agent_targets_conditional_updates?: boolean;
+  /** Server-verified canonical Notis account id used to scope local mirrors. */
+  user_id?: string;
+  sync_enabled: boolean;
+  last_synced_at: string | null;
+}
+
+export interface EntitlementAccessDetail {
+  status: "error";
+  code: "entitlement_upgrade_required";
+  upgrade_required: true;
+  entitlement: string;
+  required_plan: string;
+  upgrade_url: string;
+  message: string;
+  next_action: Record<string, unknown>;
+}
+
+export interface SyncPullResponse {
+  skill_sync_protocol?: number;
+  sync_scope?: string;
+  sync_namespace?: string | null;
+  skills: CloudSkill[];
+  sync_enabled: boolean;
+  last_synced_at: string | null;
+  /** Legacy servers could return a successful empty denial. Current servers
+   * return HTTP 403; either form must preserve existing local state. */
+  entitlement_access?: EntitlementAccessDetail;
+}
+
+/** A skill the server could not sync, with a user-facing reason (e.g. an invalid
+ * SKILL.md description rejected by OpenAI). One bad skill no longer fails the batch. */
+export interface SkillSyncFailure {
+  name: string;
+  error: string;
+}
+
+export interface SyncPushResponse {
+  skills: unknown[];
+  failed?: SkillSyncFailure[];
+}
+
+export const DEFAULT_AGENT_TARGETS: AgentTargets = {
+  notis: true,
+  claude_code: true,
+  cursor: true,
+  codex: true,
+};
+
+export function normalizeAgentTargets(targets?: Partial<AgentTargets> | null): AgentTargets {
+  return {
+    notis: Boolean(targets?.notis ?? DEFAULT_AGENT_TARGETS.notis),
+    claude_code: Boolean(targets?.claude_code ?? DEFAULT_AGENT_TARGETS.claude_code),
+    cursor: Boolean(targets?.cursor ?? DEFAULT_AGENT_TARGETS.cursor),
+    codex: Boolean(targets?.codex ?? DEFAULT_AGENT_TARGETS.codex),
+  };
+}

package/src/runtime/skill-sync/write-cloud-skill.ts

@@ -0,0 +1,50 @@
+import type { CloudSkill, SkillWriteOutcome } from './types';
+
+interface WriteCloudSkillDependencies {
+  downloadSkillBundle: (bundleUrl: string) => Promise<Buffer>;
+  writeCloudSkillToDisk: (skill: CloudSkill, bundleBytes?: Buffer) => Promise<SkillWriteOutcome | boolean>;
+  onWarning?: (message: string, error: unknown) => void;
+}
+
+export async function writeCloudSkillWithBundleFallback(
+  skill: CloudSkill,
+  dependencies: WriteCloudSkillDependencies,
+): Promise<SkillWriteOutcome | boolean> {
+  if (skill.skill_source_url) {
+    try {
+      const bundleBytes = await dependencies.downloadSkillBundle(skill.skill_source_url);
+      const wroteBundleToDisk = await dependencies.writeCloudSkillToDisk(skill, bundleBytes);
+      if (wroteBundleToDisk) {
+        return wroteBundleToDisk;
+      }
+
+      dependencies.onWarning?.(
+        `Bundle sync for "${skill.name}" produced no local changes, falling back to SKILL.md payload.`,
+        new Error('Bundle write returned false'),
+      );
+    } catch (error) {
+      dependencies.onWarning?.(
+        `Failed to apply bundle sync for "${skill.name}", falling back to SKILL.md payload.`,
+        error,
+      );
+    }
+  }
+
+  if (skill.bundle_hydration_failed) {
+    dependencies.onWarning?.(
+      `Skipping markdown fallback for synced skill "${skill.name}" because its stored bundle could not be hydrated by the server.`,
+      new Error('Bundle hydration failed'),
+    );
+    return false;
+  }
+
+  try {
+    return await dependencies.writeCloudSkillToDisk(skill);
+  } catch (error) {
+    dependencies.onWarning?.(
+      `Failed to write synced skill "${skill.name}" to disk.`,
+      error,
+    );
+    return false;
+  }
+}

package/src/runtime/skill-sync-service.js

@@ -0,0 +1,109 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isValidProfileName, loadConfig } from './profiles.js';
+import { withSkillSyncLock } from './sync-skills.js';
+
+export const SKILL_SYNC_SERVICE_LABEL = 'ai.notis.skills-sync';
+const bundlePath = fileURLToPath(new URL('../../dist/skill-sync-worker.mjs', import.meta.url));
+
+function atomicWrite(target, value, mode = 0o600) {
+  mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+  const temporary = `${target}.${process.pid}.tmp`;
+  writeFileSync(temporary, value, { mode });
+  renameSync(temporary, target);
+}
+
+function xml(value) {
+  return String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+}
+
+export async function maybeInstallSkillSyncService(runtime, {
+  config = loadConfig(), install = installSkillSyncService,
+  fetchSettings, refresh,
+} = {}) {
+  if (process.platform !== 'darwin' || runtime.credentialKind !== 'oauth'
+    || config.current_profile !== runtime.profileName
+    || !['https://api.notis.ai', 'https://api-beta.notis.ai'].includes(runtime.apiBase)) return;
+  // Ordinary commands must not steal another explicitly bound account's job.
+  const plist = join(homedir(), 'Library', 'LaunchAgents', `${SKILL_SYNC_SERVICE_LABEL}.plist`);
+  if (existsSync(plist)) {
+    const saved = readFileSync(plist, 'utf8');
+    if (runtime.oauthUserId && [runtime.profileName, runtime.apiBase, runtime.oauthUserId]
+      .every(value => saved.includes(`<string>${xml(value)}</string>`))) return install(runtime);
+    return;
+  }
+  const refreshCredential = refresh || (await import('./oauth.js')).ensureFreshOAuthCredential;
+  await refreshCredential(runtime);
+  const getSettings = fetchSettings || (await import('../../dist/skill-sync/index.js')).fetchSyncSettings;
+  const settings = await getSettings(runtime.apiBase, runtime.jwt);
+  if (settings.sync_enabled && settings.user_id === runtime.oauthUserId) return install(runtime);
+}
+
+export async function installSkillSyncService(runtime, options = {}) {
+  if ((options.platform || process.platform) !== 'darwin') return { status: 'unsupported_platform' };
+  if (runtime.credentialKind !== 'oauth' || !runtime.oauthUserId
+    || !['https://api.notis.ai', 'https://api-beta.notis.ai'].includes(runtime.apiBase)) {
+    return { status: 'skipped_non_personal_profile' };
+  }
+  // Registration upgrades must not kill a worker holding the filesystem lock,
+  // nor race another CLI registering the same LaunchAgent.
+  return withSkillSyncLock(() => installSkillSyncServiceLocked(runtime, options),
+    options.home ? { home: options.home } : {});
+}
+
+async function installSkillSyncServiceLocked(runtime, {
+  home = homedir(), platform = process.platform, nodePath = process.execPath,
+  source = bundlePath, run = spawnSync, uid = process.getuid?.(),
+} = {}) {
+  // A single explicitly selected personal account owns global agent folders.
+  // Development and hosted credentials must never enroll a machine-wide job.
+  if (platform !== 'darwin') return { status: 'unsupported_platform' };
+  if (runtime.credentialKind !== 'oauth' || runtime.envCredentialOverride
+    || !isValidProfileName(runtime.profileName)
+    || !['https://api.notis.ai', 'https://api-beta.notis.ai'].includes(runtime.apiBase)) {
+    return { status: 'skipped_non_personal_profile' };
+  }
+  const root = join(home, '.notis', 'skills', 'service');
+  const bundle = readFileSync(source);
+  const digest = createHash('sha256').update(bundle).digest('hex');
+  const installedBundle = join(root, 'runtime', digest, 'worker.mjs');
+  if (!existsSync(installedBundle)
+    || !readFileSync(installedBundle).equals(bundle)) atomicWrite(installedBundle, bundle, 0o500);
+  const args = [nodePath, installedBundle, runtime.profileName, runtime.apiBase, runtime.oauthUserId];
+  if (!runtime.oauthUserId) return { status: 'skipped_missing_account' };
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>Label</key><string>${SKILL_SYNC_SERVICE_LABEL}</string>
+<key>ProgramArguments</key><array>${args.map(value => `<string>${xml(value)}</string>`).join('')}</array>
+<key>WorkingDirectory</key><string>${xml(root)}</string>
+<key>StartInterval</key><integer>60</integer>
+<key>ProcessType</key><string>Background</string>
+</dict></plist>
+`;
+  const plistPath = join(home, 'Library', 'LaunchAgents', `${SKILL_SYNC_SERVICE_LABEL}.plist`);
+  const domain = `gui/${uid}`;
+  const target = `${domain}/${SKILL_SYNC_SERVICE_LABEL}`;
+  const unchanged = existsSync(plistPath) && readFileSync(plistPath, 'utf8') === plist;
+  const loaded = run('/bin/launchctl', ['print', target], { encoding: 'utf8', timeout: 5000 });
+  if (unchanged && loaded.status === 0) return { status: 'installed', intervalSeconds: 60, profile: runtime.profileName };
+  if (loaded.status === 0) {
+    const stopped = run('/bin/launchctl', ['bootout', target], { encoding: 'utf8', timeout: 5000 });
+    if (stopped.status !== 0) throw new Error('Could not update the existing automatic skill sync job');
+  }
+  atomicWrite(plistPath, plist);
+  let started;
+  // launchd may finish tearing down an old registration after bootout returns.
+  for (let attempt = 0; attempt < 10; attempt++) {
+    started = run('/bin/launchctl', ['bootstrap', domain, plistPath], { encoding: 'utf8', timeout: 5000 });
+    if (started.status === 0) break;
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  if (started?.status !== 0) throw new Error('Could not register automatic skill sync with macOS');
+  return { status: 'installed', intervalSeconds: 60, profile: runtime.profileName };
+}

package/src/runtime/source-root.js

@@ -0,0 +1,32 @@
+/**
+ * Commands that write inside a source folder first prove the folder is one.
+ *
+ * 2026-10-02: `notis spaces build .` run from the Notis repository root treated
+ * the repository as a Space source, refreshed "its" embedded SDK and deleted the
+ * canonical packages/sdk/src/presentation.tsx. A source folder is identified by
+ * a marker at its root, checked before any file is read for writing, staged,
+ * refreshed or deleted.
+ */
+import { statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { usageError } from './errors.js';
+
+// The workspace Space index (also a legacy App's config) or a pulled Space's lock.
+export const SOURCE_ROOT_MARKERS = Object.freeze(['notis.config.ts', 'notis.config.js', 'notis.config.mjs', '.notis/space-lock.json']);
+
+export function isSourceRoot(directory) {
+  return SOURCE_ROOT_MARKERS.some((name) => {
+    try { return statSync(join(directory, name)).isFile(); } catch { return false; }
+  });
+}
+
+/** Return the resolved folder, or refuse before anything inside it is touched. */
+export function assertSourceRoot(directory) {
+  const root = resolve(directory);
+  if (!isSourceRoot(root)) {
+    throw usageError(`${root} is not a Space source: it has no notis.config.ts (or .js, .mjs) and no .notis/space-lock.json `
+      + 'at its root, so nothing was changed. Run the command in a Space source folder, or pass that folder.');
+  }
+  return root;
+}

package/src/runtime/space-collection-scaffold.js

@@ -0,0 +1,66 @@
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { scaffoldProject } from './app-platform.js';
+import { validateViewPath } from './space-view-manifest.js';
+import { usageError } from './errors.js';
+
+/** A local, editable collection layout. No remote database or Space mutation. */
+export async function scaffoldSpaceCollection({ projectDir, name, databaseKey, path = 'records', titleProperty = 'title' }) {
+  if (typeof databaseKey !== 'string' || !databaseKey.trim() || databaseKey.length > 200) throw usageError('Pass the portable --database-key for the database this Space links.');
+  if (typeof name !== 'string' || !name.trim() || typeof titleProperty !== 'string' || !titleProperty.trim()) throw usageError('Choose a Space name and title property.');
+  validateViewPath(path);
+  await scaffoldProject({ projectDir, appName: name });
+  mkdirSync(join(projectDir, 'spaces', 'collection'), { recursive: true });
+  writeFileSync(join(projectDir, 'notis.config.ts'), `import { defineSpaces } from '@notis/sdk/config';
+export default defineSpaces({ spaces: { collection: { definition: 'spaces/collection/space.config.ts' } } });\n`);
+  const definition = { specVersion: 2, name, description: `Browse and edit ${name} records.`, path, entry: './view.tsx', layout: '../../app/layout.tsx',
+    readableContext: `Browse ${name} records. The item parameter opens one record with its properties, collaborative body and sharing controls.`,
+    verificationFixtures: './verification.json',
+    resources: { items: { kind: 'database', key: databaseKey } },
+    collection: { database: 'items', titleProperty },
+    params: { item: { type: 'record', database: 'items', main: true, description: 'The record opened beside the list.' } },
+    shows: { items: { database: 'items', where: {}, open: 'item' } },
+    memory: { markdown: true, attachments: true, screenshot: false, snapshots: [] },
+    actions: { read: { tool: 'LOCAL_NOTIS_DATABASE_QUERY', inputs: { type: 'object', additionalProperties: false,
+      required: ['request'], properties: { request: { type: 'object' } } }, arguments: { database_id: { $asset: 'items' }, request: { $input: 'request' } } } },
+  };
+  writeFileSync(join(projectDir, 'spaces/collection/space.config.ts'), `import { defineSpace } from '@notis/sdk/config';\nexport default defineSpace(${JSON.stringify(definition, null, 2)});\n`);
+  writeFileSync(join(projectDir, 'spaces/collection/view.tsx'), COLLECTION_VIEW);
+  writeFileSync(join(projectDir, 'spaces/collection/verification.json'), JSON.stringify({
+    actions: {}, shown: { items: [{ params: {}, result: { rows: [], has_more: false, schema_revision: 1 } }] },
+  }, null, 2) + '\n');
+  return { projectDir, key: 'collection', databaseKey };
+}
+
+export const COLLECTION_VIEW = `'use client';
+import { DocumentPage, useNotis, useNotisNavigation, useNotisRuntime, usePrefetchRecord, useShown, useViewParams, ViewSkeleton } from '@notis/sdk';
+import definition from './space.config';
+import { Button } from '@/components/ui/button';
+
+const copy = {
+  en: { empty: 'No records yet.', all: 'All records', untitled: 'Untitled', retry: 'Retry' },
+  fr: { empty: 'Aucun enregistrement pour le moment.', all: 'Tous les enregistrements', untitled: 'Sans titre', retry: 'Réessayer' },
+};
+export default function CollectionView() {
+  const runtime = useNotisRuntime();
+  const t = copy[runtime?.context.locale === 'fr' ? 'fr' : 'en'];
+  const { resource } = useNotis();
+  const navigation = useNotisNavigation();
+  const { params } = useViewParams<typeof definition>();
+  const { data, loading, error, refetch } = useShown<{ record_key: string; title: string | null }>('items');
+  const prefetch = usePrefetchRecord();
+  // A record is the main content: the host's document page (breadcrumb back here, title, properties, body).
+  if (params.item) return <DocumentPage recordKey={params.item} onSaved={refetch}
+    breadcrumb={[{ label: t.all, onSelect: () => resource && navigation.toSpace(resource.id) }]} />;
+  return <main className="notis-app-shell space-y-2">
+    {error ? <div role="alert">{error.message}<Button onClick={refetch}>{t.retry}</Button></div> : null}
+    {loading ? <ViewSkeleton variant="table" rows={5} /> : null}
+    {data?.rows.length === 0 ? <p className="text-sm text-muted-foreground">{t.empty}</p> : null}
+    {data?.rows.map(record => <Button key={record.record_key} variant="ghost" className="w-full justify-start truncate"
+      onPointerEnter={() => prefetch(record.record_key)} onFocus={() => prefetch(record.record_key)}
+      onClick={() => resource && navigation.toSpace(resource.id, { recordKey: record.record_key })}>
+      {record.title || t.untitled}
+    </Button>)}
+  </main>;
+}
+`;

package/src/runtime/space-database-structures.js

@@ -0,0 +1,229 @@
+/** Refresh only pulled database creation declarations; never execute authored code. */
+import { parse } from '@babel/parser';
+import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { usageError } from './errors.js';
+
+const nameOf = node => node?.type === 'Identifier' ? node.name : node?.type === 'StringLiteral' ? node.value : null;
+
+export function refreshDatabaseStructures(projectDir, localKey, structures) {
+  return refreshSpaceAuthoring(projectDir, localKey, { databaseStructures: structures });
+}
+
+/** Exact current-host overrides for copied source. Archives remain byte-preserved. */
+export function refreshSpaceAuthoring(projectDir, localKey, { databaseStructures, authoringOverrides } = {}) {
+  let rewritten = new Map();
+  if (Object.keys(databaseStructures || {}).length) rewritten = planSpaceAuthoring(projectDir, localKey, { databaseStructures }, rewritten);
+  if (authoringOverrides) rewritten = planSpaceAuthoring(projectDir, localKey, { authoringOverrides }, rewritten);
+  // Both stages must succeed before mutating even one downloaded file.
+  for (const [file, source] of rewritten) writeFileSync(file, source);
+  return [...rewritten.keys()].map(file => relative(realpathSync(projectDir), file).split(sep).join('/'));
+}
+
+function planSpaceAuthoring(projectDir, localKey, { databaseStructures: structures, authoringOverrides: overrides }, staged) {
+  const root = realpathSync(projectDir), modules = new Map();
+  const fail = () => usageError('The pulled database declaration is not statically addressable. Keep resources and create declarations as objects, local constants or relative imports; the downloaded source has not been rewritten.');
+  function load(file) {
+    file = realpathSync(file);
+    if (!file.startsWith(root + sep) || file.includes(`${sep}node_modules${sep}`)) throw fail();
+    if (modules.has(file)) return modules.get(file);
+    const source = staged.get(file) ?? readFileSync(file, 'utf8');
+    const ast = parse(source, { sourceType: 'module', plugins: ['typescript', 'jsx'] });
+    const unit = { file, source, ast, bindings: new Map(), exports: new Map() };
+    modules.set(file, unit);
+    for (const statement of ast.program.body) {
+      const declaration = statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement;
+      if (declaration?.type === 'VariableDeclaration') {
+        for (const item of declaration.declarations) if (item.id.type === 'Identifier' && item.init) {
+          unit.bindings.set(item.id.name, { node: item.init, unit });
+          if (statement.type === 'ExportNamedDeclaration') unit.exports.set(item.id.name, { node: item.init, unit });
+        }
+      }
+      if (statement.type === 'ImportDeclaration') {
+        for (const item of statement.specifiers) unit.bindings.set(item.local.name, {
+          imported: item.type === 'ImportDefaultSpecifier' ? 'default' : item.type === 'ImportNamespaceSpecifier' ? '*' : nameOf(item.imported),
+          from: statement.source.value, unit,
+        });
+      }
+      if (statement.type === 'ExportDefaultDeclaration') unit.exports.set('default', { node: statement.declaration, unit });
+      if (statement.type === 'ExportNamedDeclaration') for (const item of statement.specifiers || []) {
+        unit.exports.set(nameOf(item.exported), statement.source
+          ? { imported: nameOf(item.local), from: statement.source.value, unit }
+          : { node: item.local, unit });
+      }
+    }
+    return unit;
+  }
+  function imported(reference) {
+    if (!reference.from?.startsWith('.')) throw fail();
+    const base = resolve(dirname(reference.unit.file), reference.from);
+    const file = ['', '.ts', '.tsx', '.js', '.mjs', '/index.ts', '/index.js'].map(suffix => base + suffix).find(existsSync);
+    if (!file) throw fail();
+    return load(file);
+  }
+  function unwrap(reference, depth = 0) {
+    if (!reference || depth > 50) throw fail();
+    if (reference.from) {
+      if (reference.imported === '*') return { namespace: imported(reference) };
+      return unwrap(imported(reference).exports.get(reference.imported), depth + 1);
+    }
+    const { node, unit } = reference;
+    if (node.type === 'Identifier') return unwrap(unit.bindings.get(node.name), depth + 1);
+    if (['TSAsExpression', 'TSSatisfiesExpression', 'TSNonNullExpression', 'ParenthesizedExpression', 'TSTypeAssertion'].includes(node.type)) {
+      return unwrap({ node: node.expression, unit }, depth + 1);
+    }
+    if (node.type === 'CallExpression' && node.arguments.length === 1 && node.callee.type === 'Identifier') {
+      const helper = unit.bindings.get(node.callee.name);
+      if (helper?.from === '@notis/sdk/config' && ['defineSpace', 'defineSpaces'].includes(helper.imported)) {
+        return unwrap({ node: node.arguments[0], unit }, depth + 1);
+      }
+    }
+    if (node.type === 'MemberExpression' && (!node.computed || node.property.type === 'StringLiteral')) {
+      const object = unwrap({ node: node.object, unit }, depth + 1);
+      return object.namespace ? unwrap(object.namespace.exports.get(nameOf(node.property)), depth + 1)
+        : unwrap(property(object, nameOf(node.property), depth + 1), depth + 1);
+    }
+    return reference;
+  }
+  function property(reference, name, depth = 0) {
+    const object = unwrap(reference, depth + 1);
+    if (object.node?.type !== 'ObjectExpression') throw fail();
+    // Later properties/spreads win, exactly as the authored object does.
+    for (const entry of [...object.node.properties].reverse()) {
+      if (entry.type === 'SpreadElement') {
+        const found = property({ node: entry.argument, unit: object.unit }, name, depth + 1);
+        if (found) return found;
+      } else if (entry.type === 'ObjectProperty' && !entry.computed && nameOf(entry.key) === name) {
+        return { node: entry.value, unit: object.unit };
+      }
+    }
+    return null;
+  }
+  function scalar(reference) {
+    const value = unwrap(reference);
+    if (value.node?.type !== 'StringLiteral') throw fail();
+    return value.node.value;
+  }
+  const indexFile = ['notis.config.ts', 'notis.config.js', 'notis.config.mjs'].map(file => join(root, file)).find(existsSync);
+  if (!indexFile) throw fail();
+  const index = load(indexFile);
+  const workspace = index.exports.get('default');
+  const definition = scalar(property(property(property(workspace, 'spaces'), localKey), 'definition'));
+  const unit = load(resolve(root, definition));
+  const resources = property(unit.exports.get('default'), 'resources');
+  const edits = new Map();
+  for (const [alias, structure] of Object.entries(structures || {})) {
+    if (!structure || typeof structure.name !== 'string' || !structure.schema || typeof structure.schema !== 'object' || Array.isArray(structure.schema)) throw usageError('The server returned an incomplete live database structure.');
+    const resource = property(resources, alias);
+    if (scalar(property(resource, 'kind')) !== 'database') throw fail();
+    const create = property(resource, 'create');
+    if (!create || !Number.isInteger(create.node.start) || !Number.isInteger(create.node.end)) throw fail();
+    const list = edits.get(create.unit.file) || [];
+    // Inline declarations are edited in place. Constants retain their shared
+    // helper and get one explicit local override, not another wrapper per pull.
+    let node = create.node;
+    while (['TSAsExpression', 'TSSatisfiesExpression', 'ParenthesizedExpression'].includes(node.type)) node = node.expression;
+    if (node.type === 'ObjectExpression') {
+      const additions = [];
+      for (const [name, value] of [['name', structure.name], ['schema', structure.schema]]) {
+        const field = [...node.properties].reverse().find(item => item.type === 'ObjectProperty' && !item.computed && nameOf(item.key) === name);
+        const replacement = JSON.stringify(value, null, 2);
+        if (field && !field.shorthand) list.push({ start: field.value.start, end: field.value.end, replacement });
+        else if (field) list.push({ start: field.start, end: field.end, replacement: `${name}: ${replacement}` });
+        else additions.push(`${name}: ${replacement}`);
+      }
+      if (additions.length) list.push({ start: node.end - 1, end: node.end - 1,
+        replacement: `${node.properties.length && !create.unit.source.slice(node.properties.at(-1).end, node.end - 1).includes(',') ? ',' : ''} ${additions.join(', ')} ` });
+    } else {
+      const original = create.unit.source.slice(create.node.start, create.node.end);
+      list.push({ start: create.node.start, end: create.node.end,
+        replacement: `({ ...(${original}), name: ${JSON.stringify(structure.name)}, schema: ${JSON.stringify(structure.schema, null, 2)} })` });
+    }
+    edits.set(create.unit.file, list);
+  }
+  if (overrides) {
+    if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)
+      || Object.keys(overrides).some(key => !['record_params', 'resource_keys'].includes(key))) throw fail();
+    const recordParams = overrides.record_params || {}, resourceKeys = overrides.resource_keys || {};
+    if ([recordParams, resourceKeys].some(value => !value || typeof value !== 'object' || Array.isArray(value))) throw fail();
+    // Pin authoring to this selected definition. Shared imports/constants are
+    // overridden at their local use site, never rewritten for sibling Spaces.
+    const rootDefinition = unwrap(unit.exports.get('default'));
+    if (rootDefinition.unit !== unit || rootDefinition.node.type !== 'ObjectExpression') throw fail();
+    const rawField = name => {
+      const field = [...rootDefinition.node.properties].reverse().find(item => item.type === 'ObjectProperty'
+        && !item.computed && nameOf(item.key) === name);
+      if (!field || field.shorthand) throw fail();
+      return { node: field.value, unit };
+    };
+    const text = reference => reference.unit.source.slice(reference.node.start, reference.node.end);
+    const patchObject = (reference, fields) => {
+      let node = reference.node;
+      while (['TSAsExpression', 'TSSatisfiesExpression', 'ParenthesizedExpression'].includes(node.type)) node = node.expression;
+      if (node.type !== 'ObjectExpression') {
+        return `({ ...(${text(reference)}), ${Object.entries(fields).map(([key, value]) => `${JSON.stringify(key)}: ${value}`).join(', ')} })`;
+      }
+      let source = text(reference), changes = [], additions = [];
+      for (const [key, replacement] of Object.entries(fields)) {
+        const field = [...node.properties].reverse().find(item => item.type === 'ObjectProperty' && !item.computed && nameOf(item.key) === key);
+        if (field) changes.push({ start: (field.shorthand ? field.start : field.value.start) - reference.node.start,
+          end: (field.shorthand ? field.end : field.value.end) - reference.node.start,
+          replacement: field.shorthand ? `${JSON.stringify(key)}: ${replacement}` : replacement });
+        else additions.push(`${JSON.stringify(key)}: ${replacement}`);
+      }
+      if (additions.length) changes.push({ start: node.end - 1 - reference.node.start, end: node.end - 1 - reference.node.start,
+        replacement: `${node.properties.length && !reference.unit.source.slice(node.properties.at(-1).end, node.end - 1).includes(',') ? ',' : ''} ${additions.join(', ')} ` });
+      for (const change of changes.sort((a, b) => b.start - a.start)) source = source.slice(0, change.start) + change.replacement + source.slice(change.end);
+      return source;
+    };
+    const queue = (reference, replacement) => {
+      const list = edits.get(reference.unit.file) || [];
+      list.push({ start: reference.node.start, end: reference.node.end, replacement }); edits.set(reference.unit.file, list);
+    };
+    for (const [fieldName, requests] of [['params', recordParams], ['resources', resourceKeys]]) {
+      if (!Object.keys(requests).length) continue;
+      const reference = rawField(fieldName), object = unwrap(reference), replacements = {};
+      for (const [name, expected] of Object.entries(requests)) {
+        if (!expected || typeof expected !== 'object' || Array.isArray(expected)) throw fail();
+        const current = property(reference, name);
+        if (!current) throw fail();
+        const source = object.node.type === 'ObjectExpression' && object.unit === unit && current.unit === unit ? text(current)
+          : `(${text(reference)})[${JSON.stringify(name)}]`;
+        if (fieldName === 'params') {
+          if (Object.keys(expected).some(key => !['database', 'main'].includes(key)) || typeof expected.main !== 'boolean'
+            || scalar(property(current, 'type')) !== 'record' || scalar(property(current, 'database')) !== expected.database) throw fail();
+          replacements[name] = current.unit === unit && object.node.type === 'ObjectExpression'
+            ? patchObject(current, { main: JSON.stringify(expected.main) }) : `({ ...(${source}), main: ${JSON.stringify(expected.main)} })`;
+        } else {
+          if (Object.keys(expected).some(key => !['kind', 'key'].includes(key)) || typeof expected.key !== 'string' || !expected.key
+            || scalar(property(current, 'kind')) !== expected.kind) throw fail();
+          const create = property(current, 'create'), key = property(current, 'key');
+          if (create) {
+            // Copied source archives retain their original create declaration.
+            // A reused database (or one whose main moved) is now an existing
+            // binding: replace only this definition's resource, never a shared
+            // imported creation or a sibling view's source.
+            if (expected.kind !== 'database' || key) throw fail();
+            replacements[name] = JSON.stringify(expected);
+          } else {
+            if (!key) throw fail();
+            replacements[name] = current.unit === unit && object.node.type === 'ObjectExpression'
+              ? patchObject(current, { key: JSON.stringify(expected.key) }) : `({ ...(${source}), key: ${JSON.stringify(expected.key)} })`;
+          }
+        }
+      }
+      queue(reference, patchObject(reference, replacements));
+    }
+  }
+  const rewritten = new Map(staged);
+  for (const [file, list] of edits) {
+    let source = modules.get(file).source, previous = source.length;
+    for (const edit of list.sort((a, b) => b.start - a.start)) {
+      if (edit.end > previous) throw fail();
+      source = source.slice(0, edit.start) + edit.replacement + source.slice(edit.end); previous = edit.start;
+    }
+    parse(source, { sourceType: 'module', plugins: ['typescript', 'jsx'] });
+    rewritten.set(file, source);
+  }
+  return rewritten;
+}