@smallpen/local-package 0.1.0-alpha.5 → 0.1.0-alpha.9

package/src/local-package.mjs

@@ -23,6 +23,7 @@ import { promisify } from "node:util";
 
 import {
   canonicalJSON,
+  checkOperationShape,
   fail,
   listPackageEntries,
   loadPackageFromValues,
@@ -692,7 +693,29 @@ async function commitCandidate(originalPath, candidatePath, transactionPath) {
   await cleanup([backupPath, transactionPath, journalPath]);
 }
 
-async function applyOperationBatchLocked(locator, batch) {
+// A Product's set-active-token-themes may name its Foundation's themes; a
+// caller that did not load the Foundation (the Web backend) gets it here.
+async function themeSelectionDependencies(locator, before, batch, dependencies) {
+  if (
+    dependencies.foundation ||
+    before.manifest.role !== "product" ||
+    !batch?.operations?.some?.((operation) => operation?.type === "set-active-token-themes")
+  ) {
+    return dependencies;
+  }
+  const dependency = before.manifest.dependencies[0];
+  try {
+    const foundation = await openPackageUnlocked(join(dirname(locator), dependency.path));
+    return foundation.manifest.packageId === dependency.packageId
+      ? { ...dependencies, foundation }
+      : dependencies;
+  } catch (error) {
+    if (error instanceof SmallPenError) return dependencies;
+    throw error;
+  }
+}
+
+async function applyOperationBatchLocked(locator, batch, dependencies = {}) {
   const before = await openPackageUnlocked(locator);
   const blobWrites = batch.blobs ?? new Map();
   if (!(blobWrites instanceof Map)) {
@@ -701,7 +724,11 @@ async function applyOperationBatchLocked(locator, batch) {
   for (const [entry, bytes] of blobWrites) {
     before.blobs.set(entry, bytes);
   }
-  const prepared = await prepareOperationBatch(before, batch);
+  const prepared = await prepareOperationBatch(
+    before,
+    batch,
+    await themeSelectionDependencies(locator, before, batch, dependencies),
+  );
   const referencedBlobs = new Set(
     prepared.snapshot.manifest.entries.assets.flatMap((entry) =>
       [
@@ -826,12 +853,13 @@ function hashCanonical(value) {
 function batchIdentityHash(batch) {
   return hashCanonical({
     baseRevision: batch.baseRevision ?? null,
-    operations: batch.operations ?? [],
+    operations: batch.operations,
+    ...(batch.cliIntent ? { cliIntent: batch.cliIntent } : {}),
   });
 }
 
 function batchOperationsHash(batch) {
-  return hashCanonical({ operations: batch.operations ?? [] });
+  return hashCanonical({ operations: batch.operations });
 }
 
 // SP-039/040: a batch ledger beside the Package gives the public CLI stable
@@ -854,15 +882,13 @@ async function recordedBatchReplay(ledger, batch, readRevision, options = {}) {
   const recorded = ledger[batchId];
   if (!recorded || typeof recorded !== "object") return undefined;
   const operationsHash = await batchOperationsHash(batch);
-  const sameBatch =
-    typeof recorded.identityHash === "string"
-      ? recorded.identityHash === (await batchIdentityHash(batch))
-      : // Entries written before identities carried the base revision.
-        recorded.operationsHash === operationsHash;
+  const sameBatch = recorded.identityHash === (await batchIdentityHash(batch));
   const sameCommandRetry =
+    typeof recorded.identityHash === "string" &&
     options.rebuilt === true &&
-    recorded.operationsHash === operationsHash &&
-    batch.baseRevision === recorded.revision;
+    (recorded.operationsHash === operationsHash ||
+      (batch.cliIntent && recorded.cliIntentHash === await hashCanonical(batch.cliIntent))) &&
+    typeof batch.baseRevision === "string";
   if (!sameBatch && !sameCommandRetry) {
     fail(
       "batch_id_conflict",
@@ -877,9 +903,13 @@ async function recordedBatchReplay(ledger, batch, readRevision, options = {}) {
   }
   const currentRevision = await readRevision();
   if (currentRevision === recorded.revision) {
+    batch.operations.forEach(checkOperationShape);
     return { ...recorded.result, alreadyApplied: true };
   }
-  if (sameBatch && currentRevision === batch.baseRevision) return undefined;
+  if (
+    (sameBatch && currentRevision === batch.baseRevision) ||
+    (sameCommandRetry && recorded.baseRevision === currentRevision && batch.baseRevision === currentRevision)
+  ) return undefined;
   fail(
     "batch_superseded",
     "Batch ID was already committed, and later writes changed the Package",
@@ -897,6 +927,26 @@ function currentRevisionReader(packagePath) {
   return async () => (await openPackageUnlocked(packagePath)).revision;
 }
 
+// The committed batches, oldest first: what each changed, when, from which
+// revision, and the inverse that restores the revision before it. Read
+// only; `smallpen changes` rebuilds an earlier revision from it.
+export async function readBatchHistory(locator) {
+  const resolvedPackagePath = await resolvePackageRoot(await lockTarget(locator));
+  const ledger = await readBatchLedger(resolvedPackagePath);
+  return Object.entries(ledger)
+    .map(([batchId, entry]) => ({
+      affectedIds: entry?.result?.affectedIds ?? [],
+      baseRevision: entry?.baseRevision,
+      batchId,
+      committedAt: entry?.committedAt,
+      inverseBatch: entry?.result?.inverseBatch,
+      revision: entry?.revision ?? entry?.result?.revision,
+      // CLI writes carry the intent that produced them; App edits do not.
+      source: entry?.cliIntentHash ? "cli" : "app",
+    }))
+    .sort((left, right) => String(left.committedAt ?? "").localeCompare(String(right.committedAt ?? "")));
+}
+
 // Public replay check used by the CLI before stale-revision validation and
 // before high-level commands rebuild a batch: a committed batch identity
 // replays its recorded confirmation instead of failing or writing again.
@@ -947,13 +997,19 @@ export async function applyOperationBatch(locator, batch, options = {}) {
       currentRevisionReader(resolvedPackagePath),
     );
     if (!result) {
-      result = await applyOperationBatchLocked(resolvedPackagePath, batch);
+      result = await applyOperationBatchLocked(
+        resolvedPackagePath,
+        batch,
+        options.dependencies,
+      );
       if (Array.isArray(batch?.operations)) {
         try {
           ledger[batch.batchId] = {
+            baseRevision: batch.baseRevision,
             committedAt: new Date().toISOString(),
             identityHash: await batchIdentityHash(batch),
             operationsHash: await batchOperationsHash(batch),
+            ...(batch.cliIntent ? { cliIntentHash: await hashCanonical(batch.cliIntent) } : {}),
             result,
             revision: result.revision,
           };

package/src/local-workspace-session.mjs

@@ -1,6 +1,7 @@
+import { randomUUID } from "node:crypto";
 import { dirname, join, resolve } from "node:path";
 
-import { SmallPenError } from "@smallpen/core";
+import { followedVariantOperations, SmallPenError } from "@smallpen/core";
 
 import { LocalPackageBackend } from "./local-package-backend.mjs";
 import {
@@ -258,7 +259,10 @@ export class LocalWorkspaceSession {
   async commit(locator, batch) {
     const session = this.#required(locator);
     this.#assertWorkspaceWritable(session);
+    const before = session.backend.snapshot;
     const result = await session.backend.commit(batch);
+    const followed = await this.#followVariants(session, before);
+    if (followed.length > 0) result.followedVariants = followed;
     await this.#openLinkedPackages(session.backend.snapshot);
     await this.#updateWorkspaceStatus(session);
     session.viewState = reconcilePackageViewState(
@@ -278,7 +282,10 @@ export class LocalWorkspaceSession {
   async undo(locator) {
     const session = this.#required(locator);
     this.#assertWorkspaceWritable(session);
+    const before = session.backend.snapshot;
     const result = await session.backend.undo();
+    const followed = await this.#followVariants(session, before);
+    if (followed.length > 0) result.followedVariants = followed;
     await this.#updateWorkspaceStatus(session);
     session.viewState = reconcilePackageViewState(
       session.backend.snapshot,
@@ -292,7 +299,10 @@ export class LocalWorkspaceSession {
   async redo(locator) {
     const session = this.#required(locator);
     this.#assertWorkspaceWritable(session);
+    const before = session.backend.snapshot;
     const result = await session.backend.redo();
+    const followed = await this.#followVariants(session, before);
+    if (followed.length > 0) result.followedVariants = followed;
     await this.#updateWorkspaceStatus(session);
     session.viewState = reconcilePackageViewState(
       session.backend.snapshot,
@@ -425,6 +435,50 @@ export class LocalWorkspaceSession {
     }
   }
 
+  // A write renamed variant values in a Package other open Packages use:
+  // each of those re-points its Instances to the same variants in a batch
+  // of its own (its own undo entry), so it never turns stale for a rename.
+  // Instances of deleted variants stay for Repair. Returns what followed.
+  async #followVariants(session, before) {
+    const after = session.backend.snapshot;
+    if (!before || !after || before === after) return [];
+    const followed = [];
+    for (const dependent of this.#dependentSessions(session)) {
+      const snapshot = dependent.backend.snapshot;
+      if (!snapshot) continue;
+      const operations = followedVariantOperations(before, after, snapshot);
+      if (operations.length === 0) continue;
+      try {
+        const result = await dependent.backend.commit({
+          baseRevision: snapshot.revision,
+          batchId: `follow_variants_${randomUUID()}`,
+          operations,
+        });
+        followed.push({
+          batchId: result.batchId,
+          instances: operations.length,
+          locator: dependent.locator,
+          revision: result.revision,
+        });
+        await this.#updateWorkspaceStatus(dependent);
+        this.#emit({
+          change: dependent.backend.changes.at(-1),
+          locator: dependent.locator,
+          result,
+          type: "package-committed",
+        });
+      } catch (error) {
+        // The dependent stays as it was; its Instances show in Repair.
+        followed.push({
+          error: { code: error?.code ?? "follow_variants_failed", message: error?.message },
+          instances: operations.length,
+          locator: dependent.locator,
+        });
+      }
+    }
+    return followed;
+  }
+
   // Every open Package whose composite Workspace includes the changed one,
   // directly or through a Foundation or Library chain.
   #dependentSessions(changed) {

package/src/migrate-themes.mjs

@@ -0,0 +1,116 @@
+// `smallpen migrate-themes`: ADR 0003 upgrade by copy. The original Package
+// (or Foundation + Product pair) stays untouched; the converted copy is
+// written beside it in one rename.
+import { cp, mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+
+import {
+  canonicalJSON,
+  migrateTokenThemes,
+  SmallPenError,
+} from "@smallpen/core";
+
+import { pathExists } from "./fs-utils.mjs";
+import { openWorkspace } from "./workspace.mjs";
+
+async function writePackage(packagePath, { deletedEntries, entries, manifest }) {
+  await writeFile(join(packagePath, "manifest.json"), canonicalJSON(manifest), "utf8");
+  for (const [entry, value] of Object.entries(entries)) {
+    const output = join(packagePath, entry);
+    await mkdir(dirname(output), { recursive: true });
+    await writeFile(output, canonicalJSON(value), "utf8");
+  }
+  for (const entry of deletedEntries) {
+    if (Object.hasOwn(entries, entry)) continue;
+    await rm(join(packagePath, entry), { force: true });
+  }
+}
+
+export async function migrateThemesByCopy(locator, outputLocator) {
+  if (typeof outputLocator !== "string" || outputLocator.length === 0) {
+    throw new SmallPenError(
+      "missing_migration_output",
+      "migrate-themes requires --output NEW_PATH; the original is never changed",
+    );
+  }
+  const workspace = await openWorkspace(locator);
+  const { foundation, product } = workspace;
+  const pair = Boolean(foundation) && foundation !== product;
+  const outputPath = resolve(outputLocator);
+  if (!pair && !outputPath.toLowerCase().endsWith(".smallpen")) {
+    throw new SmallPenError(
+      "invalid_package_path",
+      "--output must be a new <name>.smallpen path for a single Package",
+      { outputPath },
+    );
+  }
+  if (await pathExists(outputPath)) {
+    throw new SmallPenError(
+      "migration_output_exists",
+      `Migration output already exists: ${outputPath}`,
+      { outputPath },
+    );
+  }
+  const result = migrateTokenThemes({ foundation, product });
+  const parent = dirname(outputPath);
+  await mkdir(parent, { recursive: true });
+  const transactionPath = await mkdtemp(join(parent, ".smallpen-migrate-"));
+  const candidatePath = join(transactionPath, basename(outputPath));
+  const dependency = pair
+    ? product.manifest.dependencies.find(
+        ({ packageId }) => packageId === foundation.manifest.packageId,
+      )
+    : undefined;
+  // Package directory of each migrated Package, relative to candidatePath.
+  const targets = new Map(
+    pair
+      ? [
+          [foundation.manifest.packageId, dependency.path],
+          [product.manifest.packageId, basename(product.locator)],
+        ]
+      : [[product.manifest.packageId, "."]],
+  );
+  const sources = new Map(
+    [foundation, product].filter(Boolean).map((snapshot) => [
+      snapshot.manifest.packageId,
+      snapshot.locator,
+    ]),
+  );
+  try {
+    for (const migrated of result.packages) {
+      const target = join(candidatePath, targets.get(migrated.packageId));
+      // Copy everything first so blobs and other files travel along.
+      await cp(sources.get(migrated.packageId), target, { recursive: true });
+      await writePackage(target, migrated);
+    }
+    const productTarget = join(candidatePath, targets.get(product.manifest.packageId));
+    const opened = await openWorkspace(productTarget);
+    await rename(candidatePath, outputPath);
+    await rm(transactionPath, { force: true, recursive: true });
+    const finalPath = (packageId) => join(outputPath, targets.get(packageId));
+    return {
+      original: pair
+        ? { foundationPath: foundation.locator, productPath: product.locator }
+        : { packagePath: product.locator },
+      output: pair
+        ? {
+            foundationPath: finalPath(foundation.manifest.packageId),
+            productPath: finalPath(product.manifest.packageId),
+            workspacePath: outputPath,
+          }
+        : { packagePath: outputPath },
+      packages: [opened.foundation, opened.product]
+        .filter(Boolean)
+        .map((snapshot) => ({
+          packageId: snapshot.manifest.packageId,
+          revision: snapshot.revision,
+        })),
+      status: "migrated",
+      themes: result.themes,
+      warnings: result.warnings,
+    };
+  } catch (error) {
+    await rm(transactionPath, { force: true, recursive: true });
+    throw error;
+  }
+}