@smallpen/cli 0.1.0-alpha.1 → 0.1.0-alpha.12

package/bin/read-output.mjs

@@ -0,0 +1,219 @@
+import { SmallPenError } from "@smallpen/core";
+
+// Public discovery fields are independent of the stored object shape.
+export const DISCOVERY_ITEM_FIELDS = Object.freeze([
+  "id",
+  "name",
+  "path",
+  "type",
+  "kind",
+  "category",
+  "packageId",
+  "source",
+  "revision",
+  "screenId",
+  "presentationId",
+  "platform",
+  "viewport",
+  "variantCount",
+  "presentationCount",
+  "nodeCount",
+]);
+
+export const DISCOVERY_OUTPUT = Object.freeze({
+  encoding: "compact-json",
+  itemFields: DISCOVERY_ITEM_FIELDS,
+  conditionalItemFields: {
+    visibility:
+      "Only private: reuse is limited to the owning package; omission means no restriction.",
+    deprecated:
+      "Only true: avoid new reuse; omission means no deprecation warning.",
+    replacement:
+      "Only a deprecated asset's replacement {packageId,assetId} when configured.",
+  },
+  definitions:
+    "Descriptions, editable definitions and node trees require a target read or explicit --full.",
+  compatibility:
+    "Default items use this public allowlist, never stored-object passthrough. Consumers must allow omitted optional fields and use contractRevision to refresh schemas.",
+});
+
+export function reuseStatus(item) {
+  return {
+    ...(item.visibility === "private" ? { visibility: "private" } : {}),
+    ...(item.deprecated === true ? { deprecated: true } : {}),
+    ...(item.deprecated === true && item.replacement
+      ? {
+          replacement: {
+            packageId: item.replacement.packageId,
+            assetId: item.replacement.assetId,
+          },
+        }
+      : {}),
+  };
+}
+
+export function discoverySummary(item, status = item) {
+  const summary = itemSummary(item);
+  return {
+    ...Object.fromEntries(
+      DISCOVERY_ITEM_FIELDS.filter(
+        (field) => summary[field] !== undefined && summary[field] !== "",
+      ).map((field) => [
+        field,
+        field === "viewport"
+          ? Object.fromEntries(
+              ["width", "height", "scale"]
+                .filter((key) => summary.viewport[key] !== undefined)
+                .map((key) => [key, summary.viewport[key]]),
+            )
+          : summary[field],
+      ]),
+    ),
+    ...reuseStatus(status),
+  };
+}
+
+export function pageItems(items, { limit = 20, offset = 0 } = {}) {
+  return {
+    items: items.slice(offset, offset + limit),
+    page: {
+      hasMore: offset + limit < items.length,
+      limit,
+      offset,
+      total: items.length,
+    },
+  };
+}
+
+// Discovery returns identities and counts. Definitions belong to target reads.
+export function itemSummary(item) {
+  const fields = [
+    "id",
+    "name",
+    "path",
+    "type",
+    "kind",
+    "category",
+    "description",
+    "packageId",
+    "source",
+    "revision",
+    "rootId",
+    "platform",
+    "viewport",
+    "screenId",
+    "presentationId",
+    "mainNodeId",
+    "basePresentationId",
+  ];
+  return {
+    ...Object.fromEntries(
+      fields
+        .filter((field) => item[field] !== undefined && item[field] !== "")
+        .map((field) => [field, item[field]]),
+    ),
+    ...reuseStatus(item),
+    ...(item.variants ? { variantCount: item.variants.length } : {}),
+    ...(item.presentations
+      ? { presentationCount: item.presentations.length }
+      : {}),
+    ...(item.nodes ? { nodeCount: Object.keys(item.nodes).length } : {}),
+  };
+}
+
+export function packageSummary(snapshot) {
+  const screens = snapshot.manifest.entries.screens.map(
+    (entry) => snapshot.entries[entry],
+  );
+  const presentations = screens.flatMap((screen) => screen.presentations);
+  return {
+    packageId: snapshot.manifest.packageId,
+    name: snapshot.manifest.name,
+    role: snapshot.manifest.role,
+    formatVersion: snapshot.manifest.formatVersion,
+    defaultScreenId: snapshot.manifest.defaultScreenId,
+    revision: snapshot.revision,
+    counts: {
+      components:
+        snapshot.domain.componentSets.size +
+        snapshot.domain.locatedComponents.size,
+      contextAxes: snapshot.domain.contextAxes.size,
+      contextProfiles: snapshot.domain.contextProfiles.size,
+      flows: snapshot.domain.flows.size,
+      nodes: presentations.reduce(
+        (total, presentation) => total + Object.keys(presentation.nodes).length,
+        0,
+      ),
+      presentations: presentations.length,
+      requirements: snapshot.domain.requirements.size,
+      scenarios: snapshot.domain.scenarios.size,
+      screens: screens.length,
+      // Token names; one Token has a value per theme option it sets.
+      tokens: new Set([...snapshot.domain.tokens.values()].map((token) => token.path)).size,
+      tokenValues: snapshot.domain.tokens.size,
+    },
+  };
+}
+
+function missing(kind, id) {
+  throw new SmallPenError("missing_read_target", `Unknown ${kind}: ${id}`, {
+    id,
+    kind,
+  });
+}
+
+
+// A semantic read keeps one flat node list, with child IDs instead of subtrees.
+export function semanticNodes(tree) {
+  const nodes = [];
+  const visit = (node) => {
+    if (!node) return;
+    nodes.push({
+      ...node,
+      children: (node.children ?? []).map((child) => child.id),
+    });
+    for (const child of node.children ?? []) visit(child);
+  };
+  visit(tree.root);
+  return nodes;
+}
+
+export function viewSummary(
+  read,
+  { nodeId, full = false, ...pagination } = {},
+) {
+  if (typeof read.result === "string" || read.format === "screenshot")
+    return read;
+  const projection = read.result;
+  const nodes =
+    read.format === "semantic"
+      ? semanticNodes(projection)
+      : Object.values(projection.nodes);
+  const selected = nodeId ? nodes.filter((node) => node.id === nodeId) : nodes;
+  if (nodeId && selected.length === 0) missing("projected node", nodeId);
+  const { items, page } = pageItems(
+    selected,
+    nodeId
+      ? { limit: 1 }
+      : {
+          ...pagination,
+          limit: pagination.limit ?? (full ? selected.length : 20),
+        },
+  );
+  const result =
+    read.format === "semantic"
+      ? { rootId: projection.root?.id, nodes: items, page }
+      : {
+          context: projection.context,
+          diagnostics: projection.diagnostics,
+          fallbackUsed: projection.fallbackUsed,
+          nodes: Object.fromEntries(items.map((node) => [node.id, node])),
+          page,
+          presentation: itemSummary(projection.presentation ?? {}),
+          rootId: projection.rootId,
+          screen: itemSummary(projection.screen ?? {}),
+        };
+  const { discovery, ...details } = read;
+  return { ...details, ...(!nodeId ? { discovery } : {}), result };
+}
+

package/bin/result-files.mjs

@@ -0,0 +1,232 @@
+import { createHash, randomUUID } from "node:crypto";
+import {
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir, userInfo } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { SmallPenError } from "@smallpen/core";
+import { secureWindowsDirectories } from "./windows-artifacts.mjs";
+
+export const OUTPUT_LIMIT_BYTES = 8192;
+export const RESULT_RETENTION_MS = 30 * 60 * 1000;
+const uuid = "[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}";
+const role =
+  "(?:result|render(?:-matrix-\\d{2})?|outline|spec|wireframe|text|undo|changes|evidence|matrix|validation|flow-connections|flow-verification)";
+const managedName = new RegExp(
+  `^(smallpen-\\d{13}-${uuid})-(${role}|owner-(\\d+))\\.(?:png|json|txt)(?:\\.smallpen-(\\d+)-${uuid}\\.tmp)?$`,
+);
+const artifactName = new RegExp(`^${role}\\.(?:png|json|txt)$`);
+let prefix = `smallpen-${Date.now()}-${randomUUID()}`;
+let activeMarker;
+let windowsSecured = false;
+
+function directories() {
+  const owner = process.getuid
+    ? `-${process.getuid()}`
+    : `-${createHash("sha256").update(JSON.stringify(userInfo())).digest("hex").slice(0, 16)}`;
+  const root = join(tmpdir(), `smallpen-cli${owner}`);
+  return [root, join(root, "results")];
+}
+function assertPrivate(path) {
+  const stat = lstatSync(path);
+  if (
+    !stat.isDirectory() ||
+    (process.getuid &&
+      (stat.uid !== process.getuid() || (stat.mode & 0o077) !== 0))
+  ) {
+    throw new SmallPenError(
+      "invalid_artifact_directory",
+      "CLI temporary directory must be an owned private directory",
+      { path },
+    );
+  }
+}
+export function artifactDirectory({ create = false, validate = false } = {}) {
+  const paths = directories();
+  const windowsItems = [];
+  for (const path of create || validate ? paths : []) {
+    let created = false;
+    try {
+      if (create) {
+        try {
+          mkdirSync(path, { mode: 0o700 });
+          created = true;
+        } catch (error) {
+          if (error.code !== "EEXIST") throw error;
+        }
+      }
+      assertPrivate(path);
+      windowsItems.push({ path, created });
+    } catch (error) {
+      if (
+        error instanceof SmallPenError ||
+        (!create && error.code === "ENOENT")
+      )
+        throw error;
+      throw new SmallPenError(
+        "artifact_directory_unavailable",
+        "CLI temporary directory is not writable or accessible",
+        { path, reason: error.code },
+      );
+    }
+  }
+  if (process.platform === "win32" && windowsItems.length && !windowsSecured) {
+    secureWindowsDirectories(windowsItems);
+    windowsSecured = true;
+  }
+  return paths.at(-1);
+}
+function realDestination(path) {
+  let ancestor = path;
+  while (true) {
+    try {
+      return join(realpathSync(ancestor), relative(ancestor, path));
+    } catch (error) {
+      if (
+        !["ENOENT", "ENOTDIR"].includes(error.code) ||
+        dirname(ancestor) === ancestor
+      )
+        throw error;
+      ancestor = dirname(ancestor);
+    }
+  }
+}
+function ownerAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code !== "ESRCH";
+  }
+}
+function cleanupExpired(directory) {
+  const entries = readdirSync(directory).flatMap((name) => {
+    const match = name.match(managedName);
+    if (!match) return [];
+    const path = join(directory, name);
+    try {
+      const stat = lstatSync(path);
+      if (!stat.isFile() && !stat.isSymbolicLink()) return [];
+      return [{ path, match, stat }];
+    } catch (error) {
+      if (error.code === "ENOENT") return [];
+      throw error;
+    }
+  });
+  const active = new Set(
+    entries
+      .filter(({ match }) => match[3] && ownerAlive(Number(match[3])))
+      .map(({ match }) => match[1]),
+  );
+  const cutoff = Date.now() - RESULT_RETENTION_MS;
+  for (const { path, match, stat } of entries) {
+    if (
+      stat.mtimeMs >= cutoff ||
+      active.has(match[1]) ||
+      (match[4] && ownerAlive(Number(match[4])))
+    )
+      continue;
+    try {
+      rmSync(path, { force: true });
+    } catch (error) {
+      if (error.code !== "ENOENT")
+        throw new SmallPenError(
+          "artifact_cleanup_failed",
+          "An expired CLI temporary file could not be removed",
+          { path, reason: error.code },
+        );
+    }
+  }
+}
+
+// Every invocation has unique names in one folder. Only expired recognized CLI
+// files are cleaned; caller-owned paths and unrelated files are never removed.
+export function beginArtifacts(_command, args = []) {
+  prefix = `smallpen-${Date.now()}-${randomUUID()}`;
+  const root = realDestination(directories()[0]);
+  for (const option of ["--output", "--inverse-out"]) {
+    const index = args.indexOf(option);
+    if (index < 0 || !args[index + 1] || args[index + 1].startsWith("--"))
+      continue;
+    const path = resolve(args[index + 1]);
+    const child = relative(root, realDestination(path));
+    if (
+      !child ||
+      (!isAbsolute(child) && child !== ".." && !child.startsWith(`..${sep}`))
+    ) {
+      throw new SmallPenError(
+        "reserved_output_path",
+        "Choose a retained output path outside the CLI-managed temporary tree",
+        { option, path },
+      );
+    }
+  }
+  let directory;
+  try {
+    directory = artifactDirectory({ validate: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+  cleanupExpired(directory);
+}
+export function artifactPath(kind, extension) {
+  if (!artifactName.test(`${kind}.${extension}`))
+    throw new Error(`Unknown CLI artifact: ${kind}.${extension}`);
+  const directory = artifactDirectory({ create: true });
+  if (!activeMarker) {
+    activeMarker = join(directory, `${prefix}-owner-${process.pid}.json`);
+    writeFileSync(activeMarker, "", { mode: 0o600, flag: "wx" });
+  }
+  return join(directory, `${prefix}-${kind}.${extension}`);
+}
+export function releaseArtifacts() {
+  if (!activeMarker) return;
+  try {
+    rmSync(activeMarker, { force: true });
+  } catch {}
+  activeMarker = undefined;
+}
+process.once("exit", releaseArtifacts);
+export function saveResult(bytes, extension = "json") {
+  const path = artifactPath("result", extension);
+  const temporary = `${path}.smallpen-${process.pid}-${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporary, bytes, { mode: 0o600, flag: "wx" });
+    renameSync(temporary, path);
+  } catch (error) {
+    rmSync(temporary, { force: true });
+    throw new SmallPenError(
+      "result_output_failed",
+      "Complete result could not be saved to the CLI temporary directory",
+      { path, reason: error.code },
+    );
+  }
+  return {
+    path,
+    format: extension,
+    bytes: Buffer.byteLength(bytes),
+    sha256: createHash("sha256").update(bytes).digest("hex"),
+    expiresAt: new Date(Date.now() + RESULT_RETENTION_MS).toISOString(),
+  };
+}
+export function printText(text) {
+  if (
+    Buffer.byteLength(text) <= OUTPUT_LIMIT_BYTES ||
+    process.argv.includes("--stdout")
+  ) {
+    process.stdout.write(text);
+    return;
+  }
+  const file = saveResult(text, "txt");
+  process.stdout.write(
+    `Complete text: ${file.path}\nBytes: ${file.bytes}; SHA-256: ${file.sha256}\nTemporary result: 30 minutes. Read/search it with your usual file tools, or request --stdout.\n`,
+  );
+}

package/bin/reuse-advice.mjs

@@ -0,0 +1,73 @@
+import { canonicalJSON, listEffectiveTokens } from "@smallpen/core";
+
+// Only this batch's new definitions are compared. Same-name Tokens in other
+// options are intentional theme values, not duplicate-token suggestions.
+export function definitionReuseAdvice(before, batch, options) {
+  if (
+    !batch.operations.some((operation) =>
+      ["put-set-token", "put-component-set"].includes(operation.type),
+    )
+  )
+    return [];
+  const items = [];
+  const tokens = listEffectiveTokens(before, options);
+  const components = [before, options.foundation]
+    .filter(Boolean)
+    .flatMap((snapshot) =>
+      [...snapshot.domain.componentSets.values()].map((component) => ({
+        ...component,
+        packageId: snapshot.manifest.packageId,
+      })),
+    );
+  for (const [operationIndex, operation] of batch.operations.entries()) {
+    if (
+      operation.type === "put-set-token" &&
+      !before.domain.tokens.has(operation.token.id)
+    ) {
+      const token = operation.token;
+      const similar = tokens.filter(
+        (item) =>
+          item.token.path !== token.name &&
+          item.token.type === token.type &&
+          canonicalJSON(item.value) === canonicalJSON(token.value),
+      );
+      if (similar.length)
+        items.push({
+          code: "existing_token_value",
+          operationIndex,
+          tokenId: token.id,
+          message:
+            "An existing Token has this type and value; consider reuse or a semantic alias",
+          candidates: similar
+            .slice(0, 3)
+            .map(({ target, token }) => ({ target, path: token.path })),
+        });
+    }
+    if (
+      operation.type === "put-component-set" &&
+      !before.domain.componentSets.has(operation.componentSet.id)
+    ) {
+      const component = operation.componentSet;
+      const normalize = (name) => name.toLowerCase().replace(/[\s_-]+/g, "");
+      const name = normalize(component.name);
+      const similar = components.filter(
+        (candidate) =>
+          candidate.id !== component.id &&
+          (normalize(candidate.name).includes(name) ||
+            name.includes(normalize(candidate.name))),
+      );
+      if (similar.length)
+        items.push({
+          code: "similar_component",
+          operationIndex,
+          componentId: component.id,
+          message:
+            "A similarly named component exists; inspect it before adding another",
+          candidates: similar
+            .slice(0, 3)
+            .map(({ id, name, packageId }) => ({ id, name, packageId })),
+        });
+    }
+  }
+  return items;
+}