@nuucognition/flint-cli 0.5.6-dev.4 → 0.5.6-dev.5

package/dist/chunk-JCALNZ4D.js

@@ -0,0 +1,936 @@
+import {
+  addPlateDeclaration,
+  getFlintConfigDir,
+  getPlateDeclarations,
+  nameFormats,
+  readFlintToml,
+  setPlateDeclaration
+} from "./chunk-LLLVBA4Q.js";
+
+// ../../packages/flint/dist/chunk-LCGQD7MB.js
+import { spawn } from "child_process";
+import { exec } from "child_process";
+import { mkdir, mkdtemp, readdir, readFile, rename, rm, stat, writeFile } from "fs/promises";
+import { basename, join, relative, resolve } from "path";
+import { promisify } from "util";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+var execAsync = promisify(exec);
+var DEFAULT_PLATES_SOURCE = "NUU-Cognition/plates";
+function normalizePlateName(name) {
+  return nameFormats(name.replace(/[-_]+/g, " ")).slug;
+}
+function isSlug(value) {
+  return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value);
+}
+async function fileExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getPlateStateDir(flintPath) {
+  return join(getFlintConfigDir(flintPath), "plates");
+}
+function getPlateAssetsDir(flintPath) {
+  return join(getFlintConfigDir(flintPath), "plates");
+}
+function getPlateAssetPath(flintPath, plateName) {
+  return join(getPlateAssetsDir(flintPath), plateName);
+}
+function getPlateStatePath(flintPath, plateName) {
+  return join(getPlateStateDir(flintPath), `${plateName}.json`);
+}
+async function readPlateState(flintPath, plateName) {
+  try {
+    const content = await readFile(getPlateStatePath(flintPath, plateName), "utf8");
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+async function writePlateState(flintPath, plateName, state) {
+  const dir = getPlateStateDir(flintPath);
+  await mkdir(dir, { recursive: true });
+  await writeFile(getPlateStatePath(flintPath, plateName), JSON.stringify(state, null, 2) + "\n", "utf8");
+}
+async function listPlateStates(flintPath) {
+  const dir = getPlateStateDir(flintPath);
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const states = await Promise.all(entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map(async (entry) => {
+      const plateName = entry.name.replace(/\.json$/, "");
+      const state = await readPlateState(flintPath, plateName);
+      return state ? [plateName, state] : null;
+    }));
+    return Object.fromEntries(states.filter((entry) => entry != null));
+  } catch {
+    return {};
+  }
+}
+function normalizePlateSource(nameOrSource) {
+  const trimmed = nameOrSource.trim();
+  if (trimmed.includes("/")) {
+    return trimmed;
+  }
+  return DEFAULT_PLATES_SOURCE;
+}
+function resolvePlateReleaseName(nameOrSource, source) {
+  const trimmed = nameOrSource.trim();
+  if (!trimmed.includes("/")) {
+    return normalizePlateName(trimmed);
+  }
+  const repo = basename(source).replace(/^plate-/, "");
+  if (repo === "plates") {
+    throw new Error(`Cannot infer plate name from monorepo source "${source}". Use the plate slug instead.`);
+  }
+  return normalizePlateName(repo);
+}
+function extractVersionFromTag(tag) {
+  const match = tag.match(/@(\d+\.\d+\.\d+(?:[-+][^/]+)?)$/);
+  return match?.[1] ?? null;
+}
+async function fetchPlateRelease(source, plateName, requestedVersion) {
+  const releaseTag = `plate-${plateName}@${requestedVersion}`;
+  const url = requestedVersion ? `https://api.github.com/repos/${source}/releases/tags/${encodeURIComponent(releaseTag)}` : `https://api.github.com/repos/${source}/releases`;
+  const response = await fetch(url, {
+    headers: {
+      "Accept": "application/vnd.github+json",
+      "User-Agent": "flint-cli"
+    }
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch release metadata for ${source} (${response.status})`);
+  }
+  const payload = requestedVersion ? [await response.json()] : await response.json();
+  const releases = payload.filter((release) => !release.draft && !release.prerelease).map((release) => {
+    const tag = typeof release.tag_name === "string" ? release.tag_name : "";
+    const version = extractVersionFromTag(tag);
+    const assets = Array.isArray(release.assets) ? release.assets : [];
+    const tarball = assets.find((asset) => typeof asset?.name === "string" && asset.name.endsWith(".tar.gz"));
+    const assetUrl = typeof tarball?.url === "string" ? tarball.url : "";
+    const assetName = typeof tarball?.name === "string" ? tarball.name : "";
+    if (!tag || !version || !assetUrl || !assetName || !tag.startsWith(`plate-${plateName}@`)) {
+      return null;
+    }
+    return {
+      tag,
+      version,
+      asset: {
+        name: assetName,
+        url: assetUrl
+      }
+    };
+  }).filter((release) => release != null);
+  if (releases.length === 0) {
+    throw new Error(`No release tarballs found for ${source}`);
+  }
+  if (requestedVersion) {
+    const match = releases.find((release) => release.version === requestedVersion);
+    if (!match) {
+      throw new Error(`Version ${requestedVersion} was not found for ${source}`);
+    }
+    return match;
+  }
+  return releases[0];
+}
+async function downloadPlateReleaseAsset(source, release) {
+  const tempDir = await mkdtemp("/tmp/flint-plate-release-");
+  const archivePath = join(tempDir, release.asset.name);
+  const response = await fetch(release.asset.url, {
+    headers: {
+      "Accept": "application/octet-stream",
+      "User-Agent": "flint-cli"
+    }
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to download ${source} release asset (${response.status})`);
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  await writeFile(archivePath, buffer);
+  return archivePath;
+}
+async function extractPlateArchive(archivePath) {
+  const tempDir = await mkdtemp("/tmp/flint-plate-extract-");
+  await execAsync(`tar -xzf "${archivePath}" -C "${tempDir}"`);
+  return tempDir;
+}
+function validateManifest(manifest, manifestPath) {
+  if (!manifest || typeof manifest !== "object") {
+    throw new Error(`Invalid plate.yaml at ${manifestPath}`);
+  }
+  const record = manifest;
+  const name = typeof record.name === "string" ? record.name.trim() : "";
+  const title = typeof record.title === "string" ? record.title.trim() : "";
+  const entry = typeof record.entry === "string" ? record.entry.trim() : "";
+  if (!name || !title || !entry) {
+    throw new Error(`plate.yaml is missing required fields (name, title, entry): ${manifestPath}`);
+  }
+  if (!isSlug(name)) {
+    throw new Error(`Invalid plate name "${name}" in ${manifestPath}`);
+  }
+  const tools = Array.isArray(record.tools) ? record.tools.map((tool) => {
+    if (!tool || typeof tool !== "object") {
+      throw new Error(`Invalid tool declaration in ${manifestPath}`);
+    }
+    const toolRecord = tool;
+    const toolName = typeof toolRecord.name === "string" ? toolRecord.name.trim() : "";
+    const command = typeof toolRecord.command === "string" ? toolRecord.command.trim() : "";
+    const description = typeof toolRecord.description === "string" ? toolRecord.description.trim() : "";
+    if (!toolName || !command || !description) {
+      throw new Error(`Tool declaration is missing required fields in ${manifestPath}`);
+    }
+    return { name: toolName, command, description };
+  }) : void 0;
+  const handles = Array.isArray(record.handles) ? record.handles.map((handle) => {
+    if (!handle || typeof handle !== "object") {
+      throw new Error(`Invalid handle declaration in ${manifestPath}`);
+    }
+    const handleRecord = handle;
+    const tag = typeof handleRecord.tag === "string" ? handleRecord.tag.trim() : "";
+    if (!tag) {
+      throw new Error(`Handle declaration is missing required tag in ${manifestPath}`);
+    }
+    return {
+      tag,
+      default: handleRecord.default === true
+    };
+  }) : void 0;
+  const actions = Array.isArray(record.actions) ? record.actions.map((action) => {
+    if (!action || typeof action !== "object") {
+      throw new Error(`Invalid action declaration in ${manifestPath}`);
+    }
+    const actionRecord = action;
+    const id = typeof actionRecord.id === "string" ? actionRecord.id.trim() : "";
+    const categoryValue = typeof actionRecord.category === "string" ? actionRecord.category.trim() : "";
+    const category = categoryValue === "cross-plate" || categoryValue === "universal" ? categoryValue : "universal";
+    const label = typeof actionRecord.label === "string" ? actionRecord.label.trim() : "";
+    if (!id || !label) {
+      throw new Error(`Action declaration is missing required fields in ${manifestPath}`);
+    }
+    return {
+      id,
+      category,
+      label,
+      description: typeof actionRecord.description === "string" ? actionRecord.description : void 0,
+      icon: typeof actionRecord.icon === "string" ? actionRecord.icon : void 0
+    };
+  }) : void 0;
+  return {
+    name,
+    title,
+    entry,
+    version: typeof record.version === "string" ? record.version : void 0,
+    description: typeof record.description === "string" ? record.description : void 0,
+    icon: typeof record.icon === "string" ? record.icon : void 0,
+    shard: typeof record.shard === "string" ? record.shard : void 0,
+    dev: typeof record.dev === "string" ? record.dev : void 0,
+    api: Array.isArray(record.api) ? record.api.filter((value) => typeof value === "string") : void 0,
+    handles,
+    actions,
+    tools
+  };
+}
+async function readPlateManifest(platePath) {
+  const manifestPath = join(platePath, "plate.yaml");
+  const content = await readFile(manifestPath, "utf8");
+  return validateManifest(parseYaml(content, { logLevel: "error" }), manifestPath);
+}
+function resolvePlateEntryPath(platePath, manifest) {
+  return resolve(platePath, manifest.entry);
+}
+var PLATE_SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", ".git"]);
+async function getNewestMtime(dir) {
+  let max = 0;
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (PLATE_SKIP_DIRS.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        const sub = await getNewestMtime(full);
+        if (sub > max) max = sub;
+      } else {
+        const s = await stat(full);
+        if (s.mtimeMs > max) max = s.mtimeMs;
+      }
+    }
+  } catch {
+  }
+  return max;
+}
+async function hasPlateSourceTree(platePath) {
+  return await fileExists(join(platePath, "src")) || await fileExists(join(platePath, "package.json")) || await fileExists(join(platePath, "vite.config.ts"));
+}
+async function checkPlateStale(platePath, manifest) {
+  if (!await hasPlateSourceTree(platePath)) {
+    return false;
+  }
+  const entryPath = resolvePlateEntryPath(platePath, manifest);
+  const entryStat = await stat(entryPath).catch(() => null);
+  if (!entryStat) return false;
+  const sourceMtime = await getNewestMtime(platePath);
+  return sourceMtime > entryStat.mtimeMs;
+}
+async function fetchDevManifest(devUrl) {
+  try {
+    const url = new URL("/plate.yaml", devUrl);
+    const response = await fetch(url.href, { signal: AbortSignal.timeout(2e3) });
+    if (!response.ok) return null;
+    const content = await response.text();
+    return validateManifest(parseYaml(content, { logLevel: "error" }), url.href);
+  } catch {
+    return null;
+  }
+}
+function createSyntheticPlateInfo(flintPath, plateName, state, declaration, devManifest) {
+  const inferred = nameFormats((state?.title ?? declaration?.title ?? plateName).replace(/-/g, " "));
+  const title = devManifest?.title ?? state?.title ?? declaration?.title ?? inferred.proper;
+  return {
+    declarationName: plateName,
+    directoryName: plateName,
+    path: getPlateAssetPath(flintPath, plateName),
+    built: Boolean(state?.devUrl),
+    stale: false,
+    dev: Boolean(state?.devUrl),
+    devUrl: state?.devUrl,
+    manifest: devManifest ?? {
+      name: plateName,
+      title,
+      entry: "./dist/index.html",
+      version: state?.currentVersion ?? declaration?.version ?? "0.1.0",
+      shard: state?.shard,
+      tools: [],
+      actions: [],
+      handles: []
+    }
+  };
+}
+async function scanInstalledPlates(flintPath, declarations, states) {
+  const platesDir = getPlateAssetsDir(flintPath);
+  const entries = await readdir(platesDir, { withFileTypes: true }).catch(() => []);
+  const infos = await Promise.all(entries.filter((entry) => entry.isDirectory()).map(async (entry) => {
+    const absolutePath = join(platesDir, entry.name);
+    if (!await fileExists(join(absolutePath, "plate.yaml"))) {
+      return null;
+    }
+    const manifest = await readPlateManifest(absolutePath);
+    const declarationName = Object.entries(declarations).find(
+      ([key, declaration]) => normalizePlateName(key) === normalizePlateName(manifest.name) || normalizePlateName(declaration.title ?? "") === normalizePlateName(manifest.title)
+    )?.[0] ?? manifest.name;
+    const state = states[manifest.name] ?? states[declarationName];
+    const built = await fileExists(resolvePlateEntryPath(absolutePath, manifest));
+    const stale = built ? await checkPlateStale(absolutePath, manifest) : false;
+    return {
+      declarationName,
+      directoryName: entry.name,
+      path: absolutePath,
+      built: state?.devUrl ? true : built,
+      stale,
+      dev: Boolean(state?.devUrl),
+      devUrl: state?.devUrl,
+      manifest
+    };
+  }));
+  return infos.filter((info) => info != null);
+}
+async function initPlateRepo(flintPath, plateName, url) {
+  const plate = await getPlate(flintPath, plateName);
+  if (!plate) {
+    throw new Error(`Plate not found: ${plateName}`);
+  }
+  const plateDir = plate.path;
+  const gitDir = join(plateDir, ".git");
+  const isGitRepo = await fileExists(gitDir);
+  if (!isGitRepo) {
+    await execAsync("git init", { cwd: plateDir });
+  }
+  const gitignorePath = join(plateDir, ".gitignore");
+  if (!await fileExists(gitignorePath)) {
+    await writeFile(gitignorePath, "node_modules/\ndist/\n", "utf8");
+  }
+  try {
+    const { stdout: existingRemote } = await execAsync("git remote get-url origin", { cwd: plateDir });
+    if (existingRemote.trim() !== url) {
+      await execAsync(`git remote set-url origin "${url}"`, { cwd: plateDir });
+    }
+  } catch {
+    await execAsync(`git remote add origin "${url}"`, { cwd: plateDir });
+  }
+  await execAsync("git add .", { cwd: plateDir });
+  let hasChanges = false;
+  try {
+    const { stdout: statusOut } = await execAsync("git status --porcelain", { cwd: plateDir });
+    hasChanges = statusOut.trim().length > 0;
+  } catch {
+    hasChanges = true;
+  }
+  if (hasChanges) {
+    await execAsync('git commit -m "Update plate"', { cwd: plateDir });
+  }
+  let pushed = false;
+  try {
+    await execAsync("git push -u origin main", { cwd: plateDir, timeout: 6e4 });
+    pushed = true;
+  } catch {
+    try {
+      await execAsync("git push -u origin HEAD", { cwd: plateDir, timeout: 6e4 });
+      pushed = true;
+    } catch {
+    }
+  }
+  return { initialized: !isGitRepo, pushed, platePath: plateDir };
+}
+async function clonePlateFromRepo(flintPath, name, url, targetPath) {
+  const absolutePath = resolve(flintPath, targetPath);
+  await mkdir(getPlateAssetsDir(flintPath), { recursive: true });
+  if (await fileExists(absolutePath)) {
+    throw new Error(`Plate directory already exists: ${targetPath}`);
+  }
+  try {
+    await execAsync(`git clone --depth 1 "${url}" "${absolutePath}"`, { timeout: 6e4 });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to clone plate "${name}": ${message}`);
+  }
+  const gitDir = join(absolutePath, ".git");
+  try {
+    await rm(gitDir, { recursive: true, force: true });
+  } catch {
+  }
+  return absolutePath;
+}
+async function updatePlateFromRepo(flintPath, name, url, targetPath) {
+  const absolutePath = resolve(flintPath, targetPath);
+  if (await fileExists(absolutePath)) {
+    await rm(absolutePath, { recursive: true, force: true });
+  }
+  return clonePlateFromRepo(flintPath, name, url, targetPath);
+}
+async function syncPlateRepos(flintPath, declarations) {
+  const results = [];
+  for (const [name, decl] of Object.entries(declarations)) {
+    if (!decl.repo || !decl.path) continue;
+    const absolutePath = resolve(flintPath, decl.path);
+    const exists = await fileExists(absolutePath);
+    try {
+      if (exists) {
+        results.push({ name, status: "skipped" });
+      } else {
+        await clonePlateFromRepo(flintPath, name, decl.repo, decl.path);
+        results.push({ name, status: "cloned" });
+      }
+    } catch (err) {
+      results.push({
+        name,
+        status: "error",
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  return results;
+}
+async function listPlates(flintPath) {
+  const declarations = await getPlateDeclarations(flintPath);
+  const states = await listPlateStates(flintPath);
+  const installed = await scanInstalledPlates(flintPath, declarations, states);
+  const infos = [...installed];
+  const unresolvedDevPlates = [];
+  for (const [name, declaration] of Object.entries(declarations)) {
+    if (installed.some((info) => normalizePlateName(info.manifest.name) === normalizePlateName(name))) {
+      continue;
+    }
+    const state = states[name];
+    if (state?.devUrl) {
+      unresolvedDevPlates.push({ name, state, declaration });
+    } else {
+      infos.push(createSyntheticPlateInfo(flintPath, name, state, declaration));
+    }
+  }
+  for (const [name, state] of Object.entries(states)) {
+    if (!state.devUrl) {
+      continue;
+    }
+    if (installed.some((info) => normalizePlateName(info.manifest.name) === normalizePlateName(name))) {
+      continue;
+    }
+    if (unresolvedDevPlates.some((p) => p.name === name)) {
+      continue;
+    }
+    unresolvedDevPlates.push({ name, state, declaration: declarations[name] });
+  }
+  const devManifests = await Promise.all(
+    unresolvedDevPlates.map(async (p) => {
+      const manifest = p.state?.devUrl ? await fetchDevManifest(p.state.devUrl) : null;
+      return { ...p, manifest };
+    })
+  );
+  for (const { name, state, declaration, manifest } of devManifests) {
+    infos.push(createSyntheticPlateInfo(flintPath, name, state, declaration, manifest));
+  }
+  const seenNames = /* @__PURE__ */ new Set();
+  for (const info of infos) {
+    const normalized = normalizePlateName(info.manifest.name);
+    if (seenNames.has(normalized)) {
+      throw new Error(`Duplicate plate manifest name detected: ${info.manifest.name}`);
+    }
+    seenNames.add(normalized);
+  }
+  return infos.sort((left, right) => left.manifest.title.localeCompare(right.manifest.title));
+}
+async function getPlate(flintPath, plateName) {
+  const normalized = normalizePlateName(plateName);
+  const plates = await listPlates(flintPath);
+  return plates.find(
+    (plate) => normalizePlateName(plate.declarationName) === normalized || normalizePlateName(plate.manifest.name) === normalized || normalizePlateName(plate.manifest.title) === normalized
+  ) ?? null;
+}
+function renderPlateManifestYaml(slug, title, shard) {
+  const manifest = {
+    name: slug,
+    title,
+    version: "0.1.0",
+    description: `${title} Plate`,
+    entry: "./dist/index.html",
+    dev: "./src/index.tsx",
+    api: ["GET /api/plates", "GET /api/artifacts"]
+  };
+  if (shard) {
+    manifest.shard = shard;
+  }
+  return stringifyYaml(manifest).trimEnd() + "\n";
+}
+async function createPlate(flintPath, displayName, options = {}) {
+  const { proper, slug } = nameFormats(displayName);
+  if (!proper.trim()) {
+    throw new Error("Plate name is required");
+  }
+  const existing = await getPlate(flintPath, slug);
+  if (existing) {
+    throw new Error(`Plate "${slug}" already exists`);
+  }
+  const platePath = getPlateAssetPath(flintPath, slug);
+  if (await fileExists(platePath)) {
+    throw new Error(`Plate directory already exists: ${relative(flintPath, platePath)}`);
+  }
+  await mkdir(join(platePath, "src"), { recursive: true });
+  await mkdir(join(platePath, "tools"), { recursive: true });
+  await writeFile(join(platePath, "plate.yaml"), renderPlateManifestYaml(slug, proper, options.shard), "utf8");
+  await writeFile(join(platePath, "package.json"), JSON.stringify({
+    name: `@plates/${slug}`,
+    private: true,
+    version: "0.1.0",
+    type: "module",
+    scripts: {
+      dev: "vite",
+      build: "vite build"
+    },
+    dependencies: {
+      "@nuucognition/plate-sdk": "workspace:*",
+      react: "^19.0.0",
+      "react-dom": "^19.0.0"
+    },
+    devDependencies: {
+      "@types/react": "^19.0.0",
+      "@types/react-dom": "^19.0.0",
+      "@vitejs/plugin-react": "^4.0.0",
+      typescript: "^5.0.0",
+      vite: "^6.0.0"
+    }
+  }, null, 2) + "\n", "utf8");
+  await writeFile(join(platePath, "tsconfig.json"), JSON.stringify({
+    compilerOptions: {
+      target: "ES2020",
+      useDefineForClassFields: true,
+      lib: ["DOM", "DOM.Iterable", "ES2020"],
+      allowJs: false,
+      skipLibCheck: true,
+      esModuleInterop: true,
+      allowSyntheticDefaultImports: true,
+      strict: true,
+      forceConsistentCasingInFileNames: true,
+      module: "ESNext",
+      moduleResolution: "Bundler",
+      resolveJsonModule: true,
+      isolatedModules: true,
+      noEmit: true,
+      jsx: "react-jsx"
+    },
+    include: ["src"]
+  }, null, 2) + "\n", "utf8");
+  await writeFile(join(platePath, "vite.config.ts"), `import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  base: '/plates/${slug}/',
+  plugins: [react()],
+  build: {
+    outDir: 'dist',
+  },
+});
+`, "utf8");
+  await writeFile(join(platePath, "index.html"), `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${proper}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>
+`, "utf8");
+  await writeFile(join(platePath, ".gitignore"), "node_modules/\ndist/\n", "utf8");
+  await writeFile(join(platePath, "src", "index.tsx"), `import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { getPlateContext } from '@nuucognition/plate-sdk';
+import { App } from './App';
+
+async function bootstrap() {
+  let connected = false;
+
+  try {
+    await getPlateContext();
+    connected = true;
+  } catch {
+    connected = false;
+  }
+
+  ReactDOM.createRoot(document.getElementById('root')!).render(
+    <React.StrictMode>
+      <App connected={connected} />
+    </React.StrictMode>,
+  );
+}
+
+void bootstrap();
+`, "utf8");
+  await writeFile(join(platePath, "src", "App.tsx"), `import { usePlateContext } from '@nuucognition/plate-sdk';
+
+export function App({ connected }: { connected: boolean }) {
+  let plateName = '${slug}';
+  let serverUrl = 'Not connected';
+
+  try {
+    const context = usePlateContext();
+    plateName = context.plateName;
+    serverUrl = context.serverUrl;
+  } catch {
+    // Render the disconnected state below.
+  }
+
+  return (
+    <main style={{ fontFamily: 'ui-sans-serif, system-ui, sans-serif', padding: 24 }}>
+      <h1 style={{ margin: 0, fontSize: 28 }}>${proper}</h1>
+      <p style={{ color: '#666', maxWidth: 640 }}>
+        This is the starter Plate scaffold. Replace this view with your interface.
+      </p>
+      <div style={{ border: '1px solid #ddd', borderRadius: 12, padding: 16, marginTop: 24 }}>
+        <div><strong>Plate:</strong> {plateName}</div>
+        <div><strong>SDK:</strong> {connected ? 'Connected to Steel' : 'Standalone preview mode'}</div>
+        <div><strong>Server:</strong> {serverUrl}</div>
+      </div>
+    </main>
+  );
+}
+`, "utf8");
+  await addPlateDeclaration(flintPath, slug, relative(flintPath, platePath), { title: proper });
+  return await getPlate(flintPath, slug);
+}
+async function validatePairedShard(flintPath, manifest) {
+  if (!manifest.shard) {
+    return [];
+  }
+  const config = await readFlintToml(flintPath);
+  const hasShard = Boolean(config?.shards?.[manifest.shard]);
+  if (hasShard) {
+    return [];
+  }
+  return [`${manifest.title} expects the "${manifest.shard}" shard, but it is not declared in flint.toml.`];
+}
+async function installExtractedPlate(flintPath, source, release, extractedPath, pinnedVersion) {
+  const manifest = await readPlateManifest(extractedPath);
+  const targetPath = getPlateAssetPath(flintPath, manifest.name);
+  await mkdir(getPlateAssetsDir(flintPath), { recursive: true });
+  await rm(targetPath, { recursive: true, force: true });
+  await rename(extractedPath, targetPath);
+  const previousState = await readPlateState(flintPath, manifest.name);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  await setPlateDeclaration(flintPath, manifest.name, {
+    source,
+    version: pinnedVersion ?? release.version,
+    title: manifest.title
+  });
+  await writePlateState(flintPath, manifest.name, {
+    version: 1,
+    plate: manifest.name,
+    source,
+    currentVersion: release.version,
+    installedAt: previousState?.installedAt ?? now,
+    updatedAt: now,
+    title: manifest.title,
+    shard: manifest.shard,
+    devUrl: previousState?.devUrl,
+    releaseTag: release.tag,
+    assetUrl: release.asset.url
+  });
+  const plate = await getPlate(flintPath, manifest.name);
+  if (!plate) {
+    throw new Error(`Installed plate "${manifest.name}" could not be resolved`);
+  }
+  return {
+    plate,
+    source,
+    version: release.version,
+    releaseTag: release.tag,
+    warnings: await validatePairedShard(flintPath, manifest)
+  };
+}
+async function installPlate(flintPath, nameOrSource, options = {}) {
+  const declarations = await getPlateDeclarations(flintPath);
+  const declaration = declarations[nameOrSource];
+  const source = normalizePlateSource(declaration?.source ?? nameOrSource);
+  const releaseName = resolvePlateReleaseName(declaration ? nameOrSource : nameOrSource, source);
+  const pinnedVersion = options.version ?? declaration?.version;
+  const release = await fetchPlateRelease(source, releaseName, pinnedVersion);
+  const archivePath = await downloadPlateReleaseAsset(source, release);
+  const extractedRoot = await extractPlateArchive(archivePath);
+  try {
+    return await installExtractedPlate(flintPath, source, release, extractedRoot, pinnedVersion);
+  } catch (error) {
+    await rm(extractedRoot, { recursive: true, force: true }).catch(() => {
+    });
+    throw error;
+  }
+}
+async function updatePlate(flintPath, plateName) {
+  const declarations = await getPlateDeclarations(flintPath);
+  const states = await listPlateStates(flintPath);
+  const names = plateName ? [plateName] : Array.from(/* @__PURE__ */ new Set([...Object.keys(declarations), ...Object.keys(states)]));
+  const results = [];
+  for (const name of names) {
+    const declaration = declarations[name];
+    const state = states[name];
+    const source = normalizePlateSource(declaration?.source ?? state?.source ?? name);
+    const releaseName = resolvePlateReleaseName(name, source);
+    const pinnedVersion = declaration?.version;
+    const release = await fetchPlateRelease(source, releaseName, pinnedVersion);
+    if (state?.currentVersion === release.version && !pinnedVersion) {
+      continue;
+    }
+    if (state?.currentVersion === release.version && pinnedVersion === release.version) {
+      continue;
+    }
+    const archivePath = await downloadPlateReleaseAsset(source, release);
+    const extractedRoot = await extractPlateArchive(archivePath);
+    try {
+      results.push(await installExtractedPlate(flintPath, source, release, extractedRoot, pinnedVersion));
+    } catch (error) {
+      await rm(extractedRoot, { recursive: true, force: true }).catch(() => {
+      });
+      throw error;
+    }
+  }
+  return results;
+}
+async function syncDeclaredPlates(flintPath, declarations) {
+  const plateDeclarations = declarations ?? await getPlateDeclarations(flintPath);
+  const states = await listPlateStates(flintPath);
+  const results = [];
+  for (const [name, declaration] of Object.entries(plateDeclarations)) {
+    if (!declaration.source) {
+      continue;
+    }
+    const state = states[name];
+    const targetVersion = declaration.version;
+    if (state?.currentVersion && (!targetVersion || state.currentVersion === targetVersion)) {
+      results.push({ name, status: "skipped", version: state.currentVersion });
+      continue;
+    }
+    try {
+      const installResult = await installPlate(flintPath, name, { version: targetVersion });
+      results.push({ name, status: "installed", version: installResult.version });
+    } catch (error) {
+      results.push({
+        name,
+        status: "error",
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  return results;
+}
+async function setPlateDevUrl(flintPath, plateName, devUrl) {
+  const normalized = normalizePlateName(plateName);
+  const existing = await readPlateState(flintPath, normalized);
+  const proper = nameFormats(plateName.replace(/-/g, " ")).proper;
+  const nextState = {
+    version: 1,
+    plate: normalized,
+    title: existing?.title ?? proper,
+    source: existing?.source,
+    currentVersion: existing?.currentVersion,
+    installedAt: existing?.installedAt,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    shard: existing?.shard,
+    releaseTag: existing?.releaseTag,
+    assetUrl: existing?.assetUrl,
+    devUrl
+  };
+  await writePlateState(flintPath, normalized, nextState);
+  return nextState;
+}
+async function clearPlateDevUrl(flintPath, plateName) {
+  const normalized = normalizePlateName(plateName);
+  const existing = await readPlateState(flintPath, normalized);
+  if (!existing) {
+    return null;
+  }
+  const nextState = {
+    ...existing,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    devUrl: void 0
+  };
+  await writePlateState(flintPath, normalized, nextState);
+  return nextState;
+}
+function resolveToolCommand(toolPath) {
+  if (toolPath.endsWith(".ts")) {
+    return { command: "npx", args: ["tsx", toolPath] };
+  }
+  if (toolPath.endsWith(".js") || toolPath.endsWith(".mjs")) {
+    return { command: "node", args: [toolPath] };
+  }
+  return { command: toolPath, args: [] };
+}
+function spawnBufferedProcess(command, args, options) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: {
+        ...process.env,
+        ...options.env
+      },
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const finish = (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolvePromise(result);
+    };
+    const timer = options.timeoutMs ? setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error("tool_timeout"));
+    }, options.timeoutMs) : null;
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (error) => {
+      if (timer) clearTimeout(timer);
+      reject(error);
+    });
+    child.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      finish({
+        exitCode: code ?? 1,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        command: [command, ...args].join(" ")
+      });
+    });
+  });
+}
+async function installPlateDeps(flintPath, plateName) {
+  const plate = await getPlate(flintPath, plateName);
+  if (!plate) {
+    throw new Error(`Plate not found: ${plateName}`);
+  }
+  return spawnBufferedProcess("pnpm", ["install"], { cwd: plate.path });
+}
+async function buildPlate(flintPath, plateName) {
+  const plate = await getPlate(flintPath, plateName);
+  if (!plate) {
+    throw new Error(`Plate not found: ${plateName}`);
+  }
+  const result = await spawnBufferedProcess("pnpm", ["build"], { cwd: plate.path });
+  if (result.exitCode !== 0) {
+    return result;
+  }
+  const entryPath = resolvePlateEntryPath(plate.path, plate.manifest);
+  if (!await fileExists(entryPath)) {
+    throw new Error(`Plate build did not produce entry file: ${relative(plate.path, entryPath)}`);
+  }
+  return result;
+}
+async function runPlateTool(flintPath, plateName, toolName, args = [], options = {}) {
+  const plate = await getPlate(flintPath, plateName);
+  if (!plate) {
+    throw new Error(`Plate not found: ${plateName}`);
+  }
+  const tool = plate.manifest.tools?.find((entry) => normalizePlateName(entry.name) === normalizePlateName(toolName));
+  if (!tool) {
+    throw new Error(`Tool not found: ${toolName}`);
+  }
+  const commandPath = resolve(plate.path, tool.command);
+  if (!await fileExists(commandPath)) {
+    throw new Error(`Tool command not found: ${relative(plate.path, commandPath)}`);
+  }
+  const runner = resolveToolCommand(commandPath);
+  return spawnBufferedProcess(runner.command, [...runner.args, ...args], {
+    cwd: flintPath,
+    env: {
+      FLINT_ROOT: resolve(flintPath),
+      PLATE_ROOT: plate.path,
+      PLATE_NAME: plate.manifest.name
+    },
+    timeoutMs: options.timeoutMs
+  });
+}
+async function listPlateTools(flintPath) {
+  const plates = await listPlates(flintPath);
+  return plates.flatMap((plate) => (plate.manifest.tools ?? []).map((tool) => ({ plate, tool })));
+}
+function spawnPlateDevServer(flintPath, plate) {
+  return spawn("pnpm", ["dev"], {
+    cwd: plate.path,
+    env: {
+      ...process.env,
+      FLINT_ROOT: resolve(flintPath),
+      PLATE_ROOT: plate.path,
+      PLATE_NAME: plate.manifest.name
+    },
+    stdio: "inherit"
+  });
+}
+
+export {
+  readPlateManifest,
+  initPlateRepo,
+  clonePlateFromRepo,
+  updatePlateFromRepo,
+  syncPlateRepos,
+  listPlates,
+  getPlate,
+  createPlate,
+  installPlate,
+  updatePlate,
+  syncDeclaredPlates,
+  setPlateDevUrl,
+  clearPlateDevUrl,
+  installPlateDeps,
+  buildPlate,
+  runPlateTool,
+  listPlateTools,
+  spawnPlateDevServer
+};