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

package/src/runtime/space-verification.js

@@ -0,0 +1,89 @@
+/** Frozen offline fixtures rendered by the same read-only library as CLI/service. */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { appFilesDigest } from './app-platform.js';
+import { createSpaceFixtureBroker } from './space-fixture-broker.js';
+
+// Kept for the standalone legacy worker's lifecycle tests while that diagnostic
+// entrypoint is retired. The primary verifier below never starts that worker.
+export function spaceVerificationEnvironment(environment, { configPath }) {
+  const names = ['PATH', 'HOME', 'TMPDIR', 'TEMP', 'TMP', 'LANG', 'SystemRoot', 'WINDIR', 'DISPLAY', 'XDG_RUNTIME_DIR'];
+  return { ...Object.fromEntries(names.filter(name => typeof environment[name] === 'string').map(name => [name, environment[name]])),
+    AGENT_BROWSER_CONFIG: configPath, AGENT_BROWSER_NO_WEBMCP: '1' };
+}
+
+export async function loadSpaceVerificationRenderer() {
+  const candidates = [new URL('../../dist/view-renderer/', import.meta.url), new URL('../../../view-renderer/', import.meta.url)];
+  for (const root of candidates) {
+    const entry = new URL('src/index.js', root);
+    if (!existsSync(fileURLToPath(entry))) continue;
+    const digest = createHash('sha256');
+    for (const file of ['src/renderer.js', 'src/dom.js', 'src/pool.js', 'dist/host.js', 'dist/host.css', 'dist/theme.css']) {
+      digest.update(file); digest.update(readFileSync(new URL(file, root)));
+    }
+    return { ...(await import(entry.href)), rendererDigest: digest.digest('hex') };
+  }
+  throw new Error('The shared view renderer is missing. Rebuild or reinstall this CLI package.');
+}
+
+// One browser per verification, two widths concurrently; no worker creates an
+// unbounded browser fanout. Up to two invocations may run simultaneously.
+let active = 0;
+const waiting = [];
+async function acquire(signal) {
+  if (signal?.aborted) throw new Error('Verification cancelled.');
+  if (active < 2) { active++; return; }
+  if (waiting.length >= 8) throw new Error('The local verification queue is full.');
+  await new Promise((accept, reject) => {
+    const entry = { accept: () => { signal?.removeEventListener('abort', abort); accept(); } };
+    const abort = () => { const index = waiting.indexOf(entry); if(index >= 0) waiting.splice(index, 1); reject(new Error('Verification cancelled.')); };
+    waiting.push(entry); signal?.addEventListener('abort', abort, { once: true });
+  });
+}
+function releaseSlot() { const next = waiting.shift(); if (next) next.accept(); else active--; }
+
+/** Initial deployment checks the exact captured bytes at both product widths. */
+export async function verifySpaceRelease(release, { capabilities, timeoutMs = 45_000, signal, loadRenderer = loadSpaceVerificationRenderer,
+  authorizationMode = 'authorize_missing', unavailableActions = [] } = {}) {
+  const diagnostic = { schema: 'notis-space-render/v1', local_key: release.manifest.local_key,
+    source_digest: appFilesDigest(release.sourceFiles), artifact_digest: appFilesDigest(release.files),
+    mode: 'offline_fixtures', checked_at: new Date().toISOString(),
+    ...(authorizationMode === 'reuse_only' ? { authorization_mode: authorizationMode,
+      unavailable_actions: structuredClone(unavailableActions) } : {}) };
+  if (signal?.aborted) return { ...diagnostic, status: 'failed', errors: [{ phase: 'browser', message: 'Verification cancelled.' }] };
+  if (release.manifest.kind === 'container') return { ...diagnostic, status: 'not_applicable_container' };
+  let pool, held = false, rendererDigest;
+  const brokers = [390, 1440].map(width => ({ width, broker: null }));
+  try {
+    // Validate fixture authority before opening a browser or acquiring a slot.
+    for (const item of brokers) item.broker = createSpaceFixtureBroker({ release, capabilities, width: item.width,
+      authorizationMode, unavailableActions });
+    await acquire(signal); held = true;
+    const library = await loadRenderer(); rendererDigest = library.rendererDigest;
+    pool = library.createBrowserPool({ concurrency: 2, maxQueue: 2 });
+    const observations = await Promise.allSettled(brokers.map(async ({ width, broker }) => {
+      const result = await library.renderView({ broker, pool, outputs: ['markdown', 'screenshot'], width, timeoutMs, signal });
+      const blocked = result.blocked_calls || [];
+      return { width, mounted: true, status: blocked.length ? 'failed' : 'passed',
+        markdown_sha256: createHash('sha256').update(result.markdown).digest('hex'),
+        screenshot_sha256: createHash('sha256').update(Buffer.from(result.screenshot.data_base64, 'base64')).digest('hex'),
+        screenshot_width: result.screenshot.width, screenshot_height: result.screenshot.height,
+        rendered_at: result.rendered_at, blocked_calls: blocked };
+    }));
+    const renders = observations.map((value, index) => value.status === 'fulfilled' ? value.value : {
+      width: brokers[index].width, mounted: false, status: 'failed', error: value.reason?.code || 'render_failed',
+    });
+    const runtimeCalls = brokers.flatMap(({ width, broker }) => broker.calls.map(call => ({ width, ...call })));
+    const passed = renders.every(value => value.status === 'passed') && runtimeCalls.every(call => call.ok);
+    return { ...diagnostic, status: passed ? 'passed' : 'failed', mounted: renders.every(value => value.mounted),
+      fixture_digest: brokers[0].broker.fixtureDigest, renderer_digest: rendererDigest,
+      render_count: renders.length, browser_count: 1, renders, runtimeCalls,
+      errors: passed ? [] : [{ phase: 'renderer', message: 'At least one width or read-only fixture failed verification.' }] };
+  } catch (error) {
+    return { ...diagnostic, status: 'failed', ...(rendererDigest ? { renderer_digest: rendererDigest } : {}),
+      errors: [{ phase: 'harness', message: error.message }] };
+  } finally {
+    try { await pool?.close(); } finally { if (held) releaseSlot(); }
+  }
+}

package/src/runtime/space-verify-browser-worker.js

@@ -0,0 +1,51 @@
+/** Runs in a credential-free child process, never in the authenticated CLI. */
+import { closeAgentBrowserSessionResult, isAgentBrowserAvailable, runHarnessRoute } from './agent-browser.js';
+
+let sessionName;
+let closing;
+let started = false;
+const controller = new AbortController();
+let exitCode = 0;
+const cleanup = () => closing ||= sessionName ? closeAgentBrowserSessionResult(sessionName) : Promise.resolve({ ok: true });
+for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => {
+  exitCode = signal === 'SIGINT' ? 130 : 143;
+  controller.abort();
+  if (!started) process.exit(exitCode);
+});
+process.on('disconnect', () => { exitCode = 1; controller.abort(); if (!started) process.exit(1); });
+
+process.once('message', async input => {
+  started = true;
+  let result;
+  try {
+    const url = new URL(input.url);
+    if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || !url.port
+      || !/^notis-space-[a-f0-9-]+$/.test(input.sessionName)) throw new Error('Invalid offline verification session.');
+    sessionName = input.sessionName;
+    if (!isAgentBrowserAvailable()) throw new Error('Install agent-browser and its Chromium browser to verify a presentation.');
+    const observed = await runHarnessRoute({ url: url.href, sessionName, timeoutMs: input.timeoutMs,
+      designViewports: [], waitForRuntime: true, signal: controller.signal });
+    // Never retain raw eval/stdout or action inputs/results in a diagnostic receipt.
+    result = {
+      mounted: observed.mounted,
+      renderStarted: observed.renderStarted,
+      timed_out: Boolean(observed.timed_out),
+      errors: (observed.errors || []).map(error => ({ phase: String(error.phase).slice(0, 100), message: String(error.message).slice(0, 2000) })),
+      runtimeCalls: (observed.runtimeCalls || []).map(call => ({ actionId: call.actionId, ok: call.ok,
+        ...(call.error ? { error: String(call.error).slice(0, 2000) } : {}) })),
+      ...(observed.tool_error ? { tool_error: { phase: observed.tool_error.phase,
+        message: String(observed.tool_error.stderr || observed.tool_error.message
+          || 'The isolated verification browser could not complete this operation.').slice(0, 2000) } } : {}),
+    };
+  } catch (error) {
+    result = { mounted: false, errors: [{ phase: 'browser', message: error.message }], runtimeCalls: [] };
+  } finally {
+    if (process.connected) {
+      try { process.send({ phase: 'cleanup' }, () => {}); } catch { /* Cleanup still owns the browser after IPC loss. */ }
+    }
+    const closed = await cleanup();
+    result = { ...result, cleanup: closed, ...(!closed.ok ? { cleanup_failed: true } : {}) };
+  }
+  if (process.connected) process.send(result, () => process.exit(exitCode));
+  else process.exit(exitCode);
+});

package/src/runtime/space-view-manifest.js

@@ -0,0 +1,254 @@
+/**
+ * What a view declares (V4): path, typed params, shows, memory, chrome and a Markdown override.
+ * Mirrors server/lib/space_view_manifest.py, which re-checks every release; property-level checks
+ * need the linked schemas and run on the server during `spaces verify` and deploy.
+ * Every presentation requires path, description and memory, including sources that omit
+ * specVersion. Containers remain non-executable; explicit specVersion 2 is unchanged.
+ */
+import { usageError } from './errors.js';
+import portalRouteRoots from '../../config/portal-route-roots.json' with { type: 'json' };
+const RESERVED_PATHS = new Set(portalRouteRoots);
+
+export const VIEW_SPEC_VERSION = 2;
+export const VIEW_DEFINITION_FIELDS = Object.freeze(['specVersion', 'path', 'params', 'shows', 'memory', 'chrome', 'markdown']);
+export const VIEW_PARAM_TYPES = Object.freeze(['record', 'enum', 'text', 'number', 'date', 'boolean']);
+const RESERVED_PARAMS = new Set(['record', 'assistantThread']);
+const PAGE_ONLY = ['params', 'shows', 'memory', 'chrome', 'markdown'];
+const NAME = /^[a-z][A-Za-z0-9_]{0,63}$/;
+// Credentials never ride in links, so no view param may look like one (the Portal drops these names).
+const CREDENTIAL_PARAM = /^(?:jwt|code|state|key)$|token|secret|password|credential|session|auth|api_?key/i;
+const WORD = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const ID_TAIL = /(?:^|-)(?:[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+const PLACEHOLDER = /^\{([a-z][A-Za-z0-9_]{0,63})(?:\.([^{}.\s][^{}]{0,199}))?\}$/;
+const RECORD_KEY = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const SERVICE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f]/;
+const FIELD_KEYS = ['property', 'property_id', 'column'];
+const OPS = new Set(['equals', 'not_equals', 'in', 'contains', 'not_contains', 'starts_with', 'ends_with', 'is_empty', 'is_not_empty',
+  'greater_than', 'less_than', 'greater_than_or_equal_to', 'less_than_or_equal_to', 'does_not_contain', 'before', 'after',
+  'on_or_before', 'on_or_after']);
+const CRON_BOUNDS = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 7]];
+const DEBOUNCE = [60, 86400];
+
+const plain = value => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const text = (value, limit) => typeof value === 'string' && value.trim().length >= 1 && value.trim().length <= limit && !CONTROL.test(value);
+const isoDate = value => typeof value === 'string' && DATE.test(value) && !Number.isNaN(Date.parse(`${value}T00:00:00Z`))
+  && new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) === value;
+
+export function validateViewPath(value) {
+  if (typeof value !== 'string' || value.length < 1 || value.length > 100) {
+    throw usageError('Declare path as the words of this view\'s links, such as "notes" or "seo/keywords".');
+  }
+  const segments = value.split('/');
+  if (segments.length > 4 || segments.some(segment => !WORD.test(segment) || ID_TAIL.test(segment))) {
+    throw usageError('A path is up to four lowercase words (a-z, 0-9, dashes) separated by "/", without ids.');
+  }
+  if (RESERVED_PATHS.has(segments[0])) throw usageError(`The path "${segments[0]}" belongs to the Portal. Choose another first word.`);
+  return value;
+}
+
+function validCron(value) {
+  const fields = typeof value === 'string' ? value.split(' ') : [];
+  if (fields.length !== 5) return false;
+  return fields.every((field, index) => {
+    const [low, high] = CRON_BOUNDS[index];
+    const inRange = number => /^\d+$/.test(number) && Number(number) >= low && Number(number) <= high;
+    if (index === 0) return inRange(field);
+    return field.split(',').every(part => {
+      const [base, step, extra] = part.split('/');
+      if (extra !== undefined || (step !== undefined && !(/^\d+$/.test(step) && Number(step) >= 1 && Number(step) <= high))) return false;
+      if (base === '*') return true;
+      const [start, end, more] = base.split('-');
+      if (more !== undefined || !inRange(start) || (end !== undefined && (!inRange(end) || Number(start) > Number(end)))) return false;
+      return true;
+    });
+  });
+}
+
+function validateMemory(memory) {
+  if (!plain(memory) || Object.keys(memory).sort().join(',') !== 'attachments,markdown,screenshot,snapshots') {
+    throw usageError('Declare memory as { markdown, attachments, screenshot, snapshots }; see the memory guide.');
+  }
+  if (['markdown', 'attachments', 'screenshot'].some(name => typeof memory[name] !== 'boolean')) {
+    throw usageError('memory.markdown, memory.attachments and memory.screenshot are true or false.');
+  }
+  if (!Array.isArray(memory.snapshots) || memory.snapshots.length > 3) {
+    throw usageError('memory.snapshots lists on_render, { scheduled } and { on_change }, each at most once ([] for none).');
+  }
+  const seen = new Set();
+  for (const strategy of memory.snapshots) {
+    let kind;
+    if (strategy === 'on_render') kind = 'on_render';
+    else if (plain(strategy) && Object.keys(strategy).join(',') === 'scheduled') {
+      kind = 'scheduled';
+      if (!validCron(strategy.scheduled)) throw usageError('A scheduled snapshot uses a five-field UTC cron with a fixed minute, such as "0 7 * * 1".');
+    } else if (plain(strategy) && Object.keys(strategy).join(',') === 'on_change') {
+      kind = 'on_change';
+      const debounce = strategy.on_change?.debounceSeconds;
+      if (!plain(strategy.on_change) || Object.keys(strategy.on_change).join(',') !== 'debounceSeconds' || !Number.isInteger(debounce)
+        || debounce < DEBOUNCE[0] || debounce > DEBOUNCE[1]) {
+        throw usageError(`An on_change snapshot waits debounceSeconds (${DEBOUNCE[0]} to ${DEBOUNCE[1]}) after the last change.`);
+      }
+    } else throw usageError('memory.snapshots lists on_render, { scheduled: "<cron>" } or { on_change: { debounceSeconds } }.');
+    if (seen.has(kind)) throw usageError('Declare each memory snapshot strategy at most once.');
+    seen.add(kind);
+  }
+}
+
+/** One typed param value, as the SDK and the server accept it. */
+export function viewParamValue(declaration, value) {
+  switch (declaration.type) {
+    case 'text': return typeof value === 'string' && value.length <= 500 && !CONTROL.test(value);
+    case 'enum': return typeof value === 'string' && (declaration.values || []).includes(value);
+    case 'number': return typeof value === 'number' && Number.isFinite(value);
+    case 'boolean': return typeof value === 'boolean';
+    case 'date': return isoDate(value);
+    case 'record': return typeof value === 'string' && RECORD_KEY.test(value);
+    default: return false;
+  }
+}
+
+function validateParam(name, declaration, resources) {
+  if (!NAME.test(name) || RESERVED_PARAMS.has(name) || CREDENTIAL_PARAM.test(name)) throw usageError(`Param names are camelCase words; "${name}" is not available.`);
+  const allowed = new Set(['type', 'description', 'required', 'default', 'values', 'database', 'main', 'slugProperty']);
+  if (!plain(declaration) || Object.keys(declaration).some(field => !allowed.has(field)) || !VIEW_PARAM_TYPES.includes(declaration.type)) {
+    throw usageError(`Declare param "${name}" as { type, description, ... } with type ${VIEW_PARAM_TYPES.join(', ')}.`);
+  }
+  if (!text(declaration.description, 500)) throw usageError(`Describe param "${name}": what it selects, for agents and people.`);
+  if ('required' in declaration && typeof declaration.required !== 'boolean') throw usageError(`Param "${name}": required is true or false.`);
+  if (declaration.type === 'enum') {
+    const values = declaration.values;
+    if (!Array.isArray(values) || values.length < 1 || values.length > 100 || new Set(values).size !== values.length
+      || values.some(value => !text(value, 100))) throw usageError(`Param "${name}": an enum lists its distinct values.`);
+  } else if ('values' in declaration) throw usageError(`Param "${name}": only enum params list values.`);
+  if (declaration.type === 'record') {
+    if (resources[declaration.database]?.kind !== 'database') {
+      throw usageError(`Param "${name}": a record param names a database this Space declares in resources.`);
+    }
+    if ('main' in declaration && typeof declaration.main !== 'boolean') throw usageError(`Param "${name}": main is true or false.`);
+    if ('slugProperty' in declaration && !text(declaration.slugProperty, 200)) throw usageError(`Param "${name}": slugProperty names a property of its database.`);
+    if ('default' in declaration) throw usageError(`Param "${name}": a record param has no default record.`);
+  } else if (['database', 'main', 'slugProperty'].some(field => field in declaration)) {
+    throw usageError(`Param "${name}": database, main and slugProperty belong to record params.`);
+  }
+  if ('default' in declaration) {
+    if (declaration.required === true) throw usageError(`Param "${name}": a required param has no default.`);
+    if (!viewParamValue(declaration, declaration.default)) throw usageError(`Param "${name}": its default must be a valid ${declaration.type} value.`);
+  }
+}
+
+function checkPlaceholder(value, params, collection, where) {
+  const match = typeof value === 'string' ? PLACEHOLDER.exec(value) : null;
+  if (!match) return;
+  const [, name, property] = match;
+  if (name === 'record') {
+    const records = Object.values(params).filter(declaration => declaration.type === 'record');
+    if (records.length === 1 || (!records.length && collection)) return;
+    throw usageError('Use {record} only in a view with exactly one record param (or a collection); otherwise name the param, such as {project}.');
+  }
+  if (!Object.hasOwn(params, name)) throw usageError(`${where}: "{${name}}" names no declared param.`);
+  if (property !== undefined && params[name].type !== 'record') throw usageError(`${where}: only record params have properties, such as {${name}}.`);
+}
+
+function walkFilter(node, visit, where, depth = 0, budget = { left: 200 }) {
+  budget.left -= 1;
+  if (depth > 12 || budget.left < 0) throw usageError(`${where}: the filter is too complex; use fewer conditions.`);
+  if (depth === 0 && plain(node) && !Object.keys(node).length) return;
+  if (!plain(node)) throw usageError(`${where}: a filter is an object.`);
+  for (const group of ['and', 'or']) {
+    if (!Object.hasOwn(node, group)) continue;
+    const children = node[group];
+    if (Object.keys(node).length !== 1 || !Array.isArray(children) || !children.length) throw usageError(`${where}: filter groups need at least one condition.`);
+    children.forEach(child => walkFilter(child, visit, where, depth + 1, budget));
+    return;
+  }
+  const field = node.field;
+  if (Object.keys(node).some(key => !['field', 'op', 'value'].includes(key)) || !('field' in node) || !('op' in node)
+    || !plain(field) || Object.keys(field).length !== 1 || !FIELD_KEYS.includes(Object.keys(field)[0])
+    || typeof Object.values(field)[0] !== 'string' || !OPS.has(node.op)) {
+    throw usageError(`${where}: each condition is { field: { property }, op, value } in the native filter language.`);
+  }
+  visit(node);
+}
+
+function validateShows(name, declaration, params, resources, collection) {
+  const where = `shows.${name}`;
+  if (!NAME.test(name)) throw usageError(`Shows names are camelCase words; "${name}" is not available.`);
+  if (plain(declaration) && 'about' in declaration) {
+    const services = declaration.services ?? [];
+    if (Object.keys(declaration).some(field => !['about', 'services'].includes(field)) || !text(declaration.about, 500)
+      || !Array.isArray(services) || services.length > 20 || services.some(service => typeof service !== 'string' || !SERVICE.test(service))) {
+      throw usageError(`${where}: describe what it shows as { about, services? }.`);
+    }
+    return;
+  }
+  if (!plain(declaration) || Object.keys(declaration).some(field => !['database', 'where', 'open'].includes(field)) || !('where' in declaration)) {
+    throw usageError(`${where}: declare { database, where, open? } for Notis data or { about, services? } otherwise.`);
+  }
+  if (resources[declaration.database]?.kind !== 'database') {
+    throw usageError(`${where}: "${declaration.database}" is not a database this Space declares and links.`);
+  }
+  if (declaration.open !== undefined && (params[declaration.open]?.type !== 'record' || params[declaration.open].database !== declaration.database)) {
+    throw usageError(`${where}: open names a record param over the same database.`);
+  }
+  walkFilter(declaration.where, condition => {
+    if (!('value' in condition)) return;
+    const values = condition.op === 'in' && Array.isArray(condition.value) ? condition.value : [condition.value];
+    values.forEach(value => checkPlaceholder(value, params, collection, where));
+  }, where);
+}
+
+/**
+ * Validates V4 declarations independently of the optional version marker, then returns
+ * their manifest form without inventing a version or page fields for containers.
+ */
+export function viewManifestFields(definition, { entry, resources }) {
+  const container = !entry;
+  const version = definition.specVersion;
+  if (version !== undefined && version !== VIEW_SPEC_VERSION) throw usageError(`specVersion is ${VIEW_SPEC_VERSION} for sources that declare the view manifest.`);
+  if (container && PAGE_ONLY.some(field => definition[field] !== undefined)) {
+    throw usageError('A container has no page: params, shows, memory, chrome and markdown belong to its views.');
+  }
+  if (!container || version === VIEW_SPEC_VERSION) {
+    const missing = ['path', 'description'].filter(field => !definition[field]);
+    if (!container && definition.memory === undefined) missing.push('memory');
+    if (missing.length) throw usageError(`This view needs ${missing.join(', ')} (specVersion 2).`);
+    if (!text(definition.description, 300)) throw usageError('Describe this view in one line (up to 300 characters).');
+  }
+  if (definition.path !== undefined) validateViewPath(definition.path);
+  const params = definition.params ?? {};
+  if (definition.params !== undefined) {
+    if (!plain(params) || Object.keys(params).length > 50) throw usageError('Declare params as { name: { type, description, ... } }.');
+    const mains = new Map();
+    for (const [name, declaration] of Object.entries(params)) {
+      validateParam(name, declaration, resources);
+      if (declaration.type !== 'record' || declaration.main !== true) continue;
+      if (mains.has(declaration.database)) {
+        throw usageError(`Params "${mains.get(declaration.database)}" and "${name}" both claim main for database "${declaration.database}"; a database has one main view.`);
+      }
+      mains.set(declaration.database, name);
+    }
+  }
+  if (definition.shows !== undefined) {
+    if (!plain(definition.shows) || Object.keys(definition.shows).length > 50) {
+      throw usageError('Declare shows as { name: { database, where, open? } } or { name: { about, services? } }.');
+    }
+    for (const [name, declaration] of Object.entries(definition.shows)) validateShows(name, declaration, params, resources, definition.collection);
+  }
+  if (definition.memory !== undefined) validateMemory(definition.memory);
+  if (definition.chrome !== undefined && !['portal', 'hidden'].includes(definition.chrome)) throw usageError("chrome is 'portal' (default) or 'hidden'.");
+  if (definition.markdown !== undefined && (typeof definition.markdown !== 'string' || !definition.markdown)) {
+    throw usageError('markdown names a source module whose default export renders this view as Markdown.');
+  }
+  return {
+    ...(version !== undefined ? { spec_version: version } : {}),
+    ...(definition.path !== undefined ? { path: definition.path } : {}),
+    ...(definition.params !== undefined ? { params } : {}),
+    ...(definition.shows !== undefined ? { shows: definition.shows } : {}),
+    ...(definition.memory !== undefined ? { memory: definition.memory } : {}),
+    ...(definition.chrome !== undefined ? { chrome: definition.chrome } : {}),
+    ...(definition.markdown !== undefined ? { markdown: { export_name: 'SpaceMarkdown' } } : {}),
+  };
+}

package/src/runtime/store-screenshot.js

@@ -0,0 +1,146 @@
+import { fileURLToPath } from 'node:url';
+
+const STORE_SCREENSHOT_ASPECT = 16 / 10;
+const SHARED_BACKDROP_PATH = fileURLToPath(
+  new URL('./assets/store-screenshot-dark.png', import.meta.url),
+);
+
+const ACCENT_PALETTES = {
+  blue: { glow: '#4f7cff', glow2: '#274690' },
+  violet: { glow: '#9b87f5', glow2: '#5038a1' },
+  emerald: { glow: '#34d399', glow2: '#176b55' },
+  amber: { glow: '#f2a94a', glow2: '#8b4f20' },
+  rose: { glow: '#fb7185', glow2: '#8f3048' },
+  sky: { glow: '#38bdf8', glow2: '#176887' },
+  fuchsia: { glow: '#d946ef', glow2: '#772786' },
+  teal: { glow: '#2dd4bf', glow2: '#176e68' },
+};
+
+const ACCENT_NAMES = Object.keys(ACCENT_PALETTES);
+
+async function loadSharp() {
+  return (await import('sharp')).default;
+}
+
+function stableHash(value) {
+  let hash = 2166136261;
+  for (const character of String(value || 'notis-app')) {
+    hash ^= character.codePointAt(0);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+export function resolveStoreScreenshotAccent(accent, seed = 'notis-app') {
+  if (accent && ACCENT_PALETTES[accent]) {
+    return accent;
+  }
+  return ACCENT_NAMES[stableHash(seed) % ACCENT_NAMES.length];
+}
+
+export function storeScreenshotLayout(width = 2000, height = 1250, contentAspect = STORE_SCREENSHOT_ASPECT) {
+  const aspect = Number.isFinite(contentAspect) && contentAspect > 0
+    ? contentAspect : STORE_SCREENSHOT_ASPECT;
+  const horizontalInset = Math.max(48, Math.round(width * 0.06));
+  const verticalInset = Math.max(40, Math.round(height * 0.06));
+  let cardWidth = width - horizontalInset * 2;
+  let cardHeight = Math.round(cardWidth / aspect);
+  const maximumCardHeight = height - verticalInset * 2;
+  if (cardHeight > maximumCardHeight) {
+    cardHeight = maximumCardHeight;
+    cardWidth = Math.round(cardHeight * aspect);
+  }
+  const cardLeft = Math.round((width - cardWidth) / 2);
+  const cardTop = Math.round((height - cardHeight) / 2) - Math.round(height * 0.008);
+  return {
+    width,
+    height,
+    cardWidth,
+    cardHeight,
+    cardLeft,
+    cardTop,
+    radius: Math.max(18, Math.round(width * 0.016)),
+  };
+}
+
+async function backdropImage(layout) {
+  const sharp = await loadSharp();
+  return sharp(SHARED_BACKDROP_PATH)
+    .resize(layout.width, layout.height, { fit: 'cover', position: 'centre' })
+    .png()
+    .toBuffer();
+}
+
+function roundedRectSvg(width, height, radius, { fill = '#ffffff', stroke = null } = {}) {
+  const strokeAttribute = stroke
+    ? ` fill="none" stroke="${stroke}" stroke-width="2"`
+    : ` fill="${fill}"`;
+  return Buffer.from(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><rect x="1" y="1" width="${width - 2}" height="${height - 2}" rx="${radius}" ry="${radius}"${strokeAttribute}/></svg>`,
+  );
+}
+
+/**
+ * Composite a truthful browser capture into the deterministic Store frame.
+ * Fit the complete source pixels; never crop controls or redraw the app UI.
+ */
+export async function composeStoreScreenshot({
+  inputPath,
+  outputPath,
+  width = 2000,
+  height = 1250,
+  accent = null,
+  seed = 'notis-app',
+  focused = false,
+  theme = 'light',
+}) {
+  const sharp = await loadSharp();
+  const resolvedTheme = theme === 'dark' ? 'dark' : 'light';
+  const source = await sharp(inputPath).metadata();
+  const layout = storeScreenshotLayout(width, height, source.width / source.height);
+  const resolvedAccent = resolveStoreScreenshotAccent(accent, seed);
+
+  const roundedCapture = await sharp(inputPath)
+    .resize(layout.cardWidth, layout.cardHeight, {
+      fit: 'contain',
+      background: resolvedTheme === 'dark' ? '#09090b' : '#ffffff',
+    })
+    .composite([{
+      input: roundedRectSvg(layout.cardWidth, layout.cardHeight, layout.radius),
+      blend: 'dest-in',
+    }])
+    .png()
+    .toBuffer();
+
+  const border = roundedRectSvg(
+    layout.cardWidth,
+    layout.cardHeight,
+    layout.radius,
+    { stroke: resolvedTheme === 'dark' ? '#FFFFFF2A' : '#0F172A22' },
+  );
+
+  await sharp(await backdropImage(layout))
+    .composite([
+      { input: roundedCapture, left: layout.cardLeft, top: layout.cardTop },
+      { input: border, left: layout.cardLeft, top: layout.cardTop },
+    ])
+    .png({
+      compressionLevel: 9,
+      adaptiveFiltering: true,
+    })
+    .toFile(outputPath);
+
+  return {
+    mode: 'framed',
+    accent: resolvedAccent,
+    focused: Boolean(focused),
+    theme: resolvedTheme,
+    card: {
+      left: layout.cardLeft,
+      top: layout.cardTop,
+      width: layout.cardWidth,
+      height: layout.cardHeight,
+      radius: layout.radius,
+    },
+  };
+}

package/src/runtime/sync-skills.d.ts

@@ -0,0 +1,37 @@
+import type { BaseSkillReconcileResult } from './base-skills.js';
+
+export interface ReconcileAllSkillsResult {
+  baseSkills: string[];
+  baseInstalled: number;
+  baseLinked: number;
+  baseBackups: string[];
+}
+
+export interface SkillSyncLockOptions {
+  home?: string;
+  timeoutMs?: number;
+  staleMs?: number;
+  pollMs?: number;
+  now?: () => number;
+}
+
+export function withSkillSyncLock<T>(
+  callback: () => Promise<T> | T,
+  options?: SkillSyncLockOptions,
+): Promise<T>;
+
+export function reconcileAllSkills<T extends object>(options: {
+  serverUrl: string;
+  jwt: string;
+  honorSyncEnabled: boolean;
+  userId?: string | null;
+  home?: string;
+  runAccountSync: (
+    serverUrl: string,
+    jwt: string,
+    dependencies: Record<string, never>,
+    options: { honorSyncEnabled: boolean },
+  ) => Promise<T>;
+  reconcileBase?: (options: { userId?: string | null; home?: string }) => BaseSkillReconcileResult;
+  lockOptions?: Omit<SkillSyncLockOptions, 'home'>;
+}): Promise<T & ReconcileAllSkillsResult>;