chainlesschain 0.166.106 → 0.166.108

package/src/lib/plugin-runtime/cli-goal-drafts.js

@@ -0,0 +1,413 @@
+import fs from "node:fs";
+import path from "node:path";
+import { VERSION } from "../../constants.js";
+import { managedSettingsPath } from "../settings-loader.cjs";
+import { createProjectGoalConnection } from "../project-goal-connection.js";
+import {
+  collectGoalExtensions,
+  proposeGoalExtensionAction,
+} from "./goal-extensions.js";
+import { readGoalDraftDescription } from "./cli-goal-draft-request.js";
+import { digestBusinessObjectContent as digest } from "@chainlesschain/session-core/business-object-contract";
+import {
+  ACCESS_SCHEMA,
+  MAX_SUBMISSION_REFERENCE_BYTES,
+  validateGoalDraftAccess,
+  validateGoalDraftProposal,
+  validateGoalDraftReceipt,
+  validateGoalDraftSources,
+  createGoalDraftSubmissionReference,
+  validateGoalDraftSubmissionReference,
+} from "@chainlesschain/session-core/goal-draft-connection-contract";
+
+const HOST = Object.freeze({
+  id: "cli",
+  version: VERSION,
+  capabilities: Object.freeze(["proposal:task.description.update"]),
+});
+export const CLI_GOAL_DRAFT_SUBMISSION_SCHEMA =
+  "chainlesschain.goal-draft-submission/v1";
+export const CLI_GOAL_DRAFT_SOURCES_SCHEMA =
+  "chainlesschain.goal-draft-source-page/v1";
+export const _deps = {
+  createProjectGoalConnection,
+  collectGoalExtensions,
+  proposeGoalExtensionAction,
+};
+const same = (a, b) => digest(a) === digest(b);
+function fail(code) {
+  throw Object.assign(new Error(code), { code });
+}
+function required(value) {
+  if (
+    typeof value !== "string" ||
+    !value.trim() ||
+    value.length > 4096 ||
+    /[\u0000-\u001f\u007f]/u.test(value)
+  )
+    fail("CLI_GOAL_DRAFT_ARGUMENTS_REQUIRED");
+  return value;
+}
+function fixedOptions(raw) {
+  const options = { ...raw },
+    env = Object.freeze({ ...(options.env || process.env) });
+  const cwd = path.resolve(options.cwd || process.cwd());
+  required(options.plugin);
+  if (!["user", "project", "local"].includes(options.scope))
+    fail("CLI_GOAL_DRAFT_ARGUMENTS_REQUIRED");
+  for (const key of [
+    "connection",
+    "record",
+    "out",
+    "descriptionFile",
+    "managedSettingsFile",
+  ])
+    if (options[key] !== undefined)
+      options[key] = path.resolve(cwd, required(options[key]));
+  const policyEnv = { ...env };
+  if (policyEnv.CC_MANAGED_SETTINGS)
+    policyEnv.CC_MANAGED_SETTINGS = path.resolve(
+      cwd,
+      policyEnv.CC_MANAGED_SETTINGS,
+    );
+  return Object.freeze({
+    ...options,
+    cwd,
+    env,
+    managedSettingsFile: managedSettingsPath({
+      env: policyEnv,
+      managedSettingsFile: options.managedSettingsFile,
+    }),
+  });
+}
+function hostOptions(options) {
+  return Object.freeze({
+    cwd: options.cwd,
+    env: options.env,
+    managedSettingsFile: options.managedSettingsFile,
+    host: HOST,
+  });
+}
+function admitted(options, expected) {
+  const entry = _deps
+    .collectGoalExtensions(hostOptions(options))
+    .extensions.find(
+      (item) => item.name === options.plugin && item.scope === options.scope,
+    );
+  if (
+    !entry ||
+    !entry.declaration.proposals.includes("task.description.update")
+  )
+    fail("CLI_GOAL_DRAFT_NOT_ADMITTED");
+  const access = validateGoalDraftAccess({
+    schema: ACCESS_SCHEMA,
+    plugin: { name: entry.name, scope: entry.scope, version: entry.version },
+    declarationDigest: digest(entry.declaration),
+  });
+  if (expected && !same(access, expected))
+    fail("CLI_GOAL_DRAFT_ADMISSION_CHANGED");
+  return access;
+}
+function connected(id, options) {
+  required(id);
+  required(options.connection);
+  const connection = _deps.createProjectGoalConnection(options.connection);
+  if (
+    connection.drafts !== true ||
+    !["read", "sources", "receipt", "enqueue"].every(
+      (key) => typeof connection[key] === "function",
+    )
+  )
+    fail("CLI_GOAL_DRAFT_CONNECTION_REQUIRED");
+  if (
+    connection.goalRef.id !== id ||
+    (options.expectedStore !== undefined &&
+      options.expectedStore !== connection.goalRef.storeId)
+  )
+    fail("CLI_GOAL_STORE_MISMATCH");
+  const access = admitted(options);
+  if (
+    !same(access.plugin, connection.plugin) ||
+    access.declarationDigest !== connection.declarationDigest
+  )
+    fail("CLI_GOAL_DRAFT_CONNECTION_MISMATCH");
+  return { connection, access };
+}
+function sameFile(a, b) {
+  return (
+    a.isFile() &&
+    b.isFile() &&
+    !b.isSymbolicLink() &&
+    b.nlink === 1 &&
+    a.dev === b.dev &&
+    a.ino === b.ino &&
+    a.size === b.size &&
+    a.mtimeMs === b.mtimeMs &&
+    a.ctimeMs === b.ctimeMs
+  );
+}
+function readReference(file) {
+  const before = fs.lstatSync(file);
+  if (
+    !before.isFile() ||
+    before.isSymbolicLink() ||
+    before.nlink !== 1 ||
+    before.size > MAX_SUBMISSION_REFERENCE_BYTES
+  )
+    fail("CLI_GOAL_DRAFT_RECORD_INVALID");
+  const fd = fs.openSync(
+    file,
+    fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0),
+  );
+  try {
+    if (!sameFile(before, fs.fstatSync(fd)))
+      fail("CLI_GOAL_DRAFT_RECORD_CHANGED");
+    const bytes = Buffer.alloc(MAX_SUBMISSION_REFERENCE_BYTES + 1);
+    const length = fs.readSync(fd, bytes, 0, bytes.length, 0);
+    if (
+      length !== before.size ||
+      !sameFile(before, fs.fstatSync(fd)) ||
+      !sameFile(before, fs.lstatSync(file))
+    )
+      fail("CLI_GOAL_DRAFT_RECORD_CHANGED");
+    const reference = validateGoalDraftSubmissionReference(
+      JSON.parse(
+        new TextDecoder("utf-8", { fatal: true }).decode(
+          bytes.subarray(0, length),
+        ),
+      ),
+    );
+    return {
+      reference,
+      verify() {
+        if (!sameFile(before, fs.lstatSync(file)))
+          fail("CLI_GOAL_DRAFT_RECORD_CHANGED");
+      },
+    };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+function writeNew(file, value) {
+  const fd = fs.openSync(file, "wx", 0o600);
+  try {
+    fs.writeFileSync(fd, JSON.stringify(value));
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  // Persist the new directory entry as well on systems that support it.
+  if (process.platform !== "win32") {
+    const directory = fs.openSync(path.dirname(file), fs.constants.O_RDONLY);
+    try {
+      fs.fsyncSync(directory);
+    } finally {
+      fs.closeSync(directory);
+    }
+  }
+}
+function persistReference(file, expected) {
+  let created = false;
+  try {
+    writeNew(file, expected);
+    created = true;
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+  }
+  const saved = readReference(file);
+  if (!same(saved.reference, expected)) fail("CLI_GOAL_DRAFT_RECORD_CONFLICT");
+  return { ...saved, created };
+}
+function referenceFor(connection, access, requestId, inputDigest) {
+  return createGoalDraftSubmissionReference({
+    goalRef: connection.goalRef,
+    ...Object.fromEntries(
+      ["plugin", "declarationDigest"].map((key) => [key, access[key]]),
+    ),
+    grantRef: connection.grantRef,
+    requestId,
+    inputDigest,
+  });
+}
+function outcome(reference, file, receipt) {
+  return {
+    schema: CLI_GOAL_DRAFT_SUBMISSION_SCHEMA,
+    state: receipt?.state ?? "unknown",
+    goalRef: reference.goalRef,
+    plugin: reference.plugin,
+    declarationDigest: reference.declarationDigest,
+    grantRef: reference.grantRef,
+    requestId: reference.requestId,
+    inputDigest: reference.inputDigest,
+    proposalId: receipt?.proposalId ?? null,
+    record: file,
+  };
+}
+async function queryReceipt(connection, saved, file) {
+  saved.verify();
+  try {
+    const receipt = validateGoalDraftReceipt(
+      await connection.receipt({
+        requestId: saved.reference.requestId,
+        inputDigest: saved.reference.inputDigest,
+      }),
+    );
+    if (
+      receipt.requestId !== saved.reference.requestId ||
+      receipt.inputDigest !== saved.reference.inputDigest
+    )
+      fail("CLI_GOAL_DRAFT_RECEIPT_MISMATCH");
+    return outcome(saved.reference, file, receipt);
+  } catch {
+    return outcome(saved.reference, file);
+  }
+}
+
+/** Exports an identity label and declaration digest, never native authority. */
+export async function exportCliGoalDraftAccess(raw = {}) {
+  const options = fixedOptions(raw);
+  required(options.out);
+  const access = admitted(options);
+  writeNew(options.out, access);
+  return {
+    schema: "chainlesschain.goal-draft-access-export/v1",
+    state: "access-exported",
+    plugin: access.plugin,
+    declarationDigest: access.declarationDigest,
+    file: options.out,
+  };
+}
+export async function readCliGoalDraftSources(id, raw = {}) {
+  const options = fixedOptions(raw),
+    { connection, access } = connected(id, options);
+  if (
+    options.after !== undefined &&
+    (typeof options.after !== "string" ||
+      !/^goal-proposal-[a-f0-9]{64}$/u.test(options.after))
+  )
+    fail("CLI_GOAL_DRAFT_INVALID_CURSOR");
+  const sources = validateGoalDraftSources(
+    await connection.sources(options.after),
+  );
+  admitted(options, access);
+  return {
+    schema: CLI_GOAL_DRAFT_SOURCES_SCHEMA,
+    goalRef: connection.goalRef,
+    plugin: access.plugin,
+    declarationDigest: access.declarationDigest,
+    grantRef: connection.grantRef,
+    sources,
+  };
+}
+export async function sendCliGoalDraft(id, raw = {}) {
+  const options = fixedOptions(raw);
+  required(options.record);
+  required(options.descriptionFile);
+  const { connection, access } = connected(id, options);
+  const proposal = validateGoalDraftProposal({
+    type: "task.description.update",
+    goalRef: connection.goalRef,
+    sourceRef: options.source,
+    requestId: options.requestId,
+    title: options.title,
+    description: readGoalDraftDescription(options.descriptionFile),
+  });
+  const reference = referenceFor(
+    connection,
+    access,
+    proposal.requestId,
+    digest(proposal),
+  );
+  const saved = persistReference(options.record, reference);
+  // Existing durable identity is always reconciled. Even a not-found response
+  // does not authorize this retry path to send another mutation automatically.
+  if (!saved.created) return queryReceipt(connection, saved, options.record);
+  let nativeReceipt;
+  let dispatched = false;
+  try {
+    await _deps.proposeGoalExtensionAction(access.plugin, proposal, {
+      ...hostOptions(options),
+      async authorize(context) {
+        if (
+          context.operation !== "propose-action" ||
+          !same(context.plugin, access.plugin) ||
+          !same(context.goalRef, proposal.goalRef) ||
+          context.requestId !== proposal.requestId ||
+          context.sourceRef !== proposal.sourceRef ||
+          context.type !== proposal.type
+        )
+          return false;
+        saved.verify();
+        const current = await connection.read(id);
+        if (
+          !same(current.goalRef, proposal.goalRef) ||
+          current.status !== "active"
+        )
+          return false;
+        admitted(options, access);
+        saved.verify();
+        return true;
+      },
+      async enqueueProposal(context) {
+        const projected = validateGoalDraftProposal(
+          Object.fromEntries(
+            [
+              "type",
+              "goalRef",
+              "sourceRef",
+              "requestId",
+              "title",
+              "description",
+            ].map((key) => [key, context[key]]),
+          ),
+        );
+        if (
+          !same(context.plugin, access.plugin) ||
+          context.operation !== "propose-action" ||
+          context.state !== "pending-confirmation" ||
+          !same(projected, proposal)
+        )
+          fail("CLI_GOAL_DRAFT_CONTEXT_CHANGED");
+        admitted(options, access);
+        saved.verify();
+        dispatched = true;
+        const receipt = validateGoalDraftReceipt(
+          await connection.enqueue(projected),
+        );
+        if (
+          receipt.state !== "saved" ||
+          receipt.requestId !== reference.requestId ||
+          receipt.inputDigest !== reference.inputDigest
+        )
+          fail("CLI_GOAL_DRAFT_RECEIPT_MISMATCH");
+        nativeReceipt = receipt;
+        return {
+          proposalId: receipt.proposalId,
+          state: "pending-confirmation",
+        };
+      },
+    });
+    if (!nativeReceipt) fail("CLI_GOAL_DRAFT_RECEIPT_MISMATCH");
+    // A verified saved receipt is not undone by a later local admission change.
+    return outcome(reference, options.record, nativeReceipt);
+  } catch (error) {
+    if (nativeReceipt) return outcome(reference, options.record, nativeReceipt);
+    if (dispatched || error.outcomeUnknown)
+      return outcome(reference, options.record);
+    throw error;
+  }
+}
+export async function readCliGoalDraftReceipt(id, raw = {}) {
+  const options = fixedOptions(raw);
+  required(options.record);
+  const { connection, access } = connected(id, options),
+    saved = readReference(options.record);
+  const expected = referenceFor(
+    connection,
+    access,
+    saved.reference.requestId,
+    saved.reference.inputDigest,
+  );
+  if (!same(expected, saved.reference)) fail("CLI_GOAL_DRAFT_RECORD_CONFLICT");
+  return queryReceipt(connection, saved, options.record);
+}

package/src/lib/plugin-runtime/cli-goal-extension-host.js

@@ -0,0 +1,234 @@
+/** Explicit goal panels from standalone files or a short-lived desktop read lease. */
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { VERSION } from "../../constants.js";
+import { resolveConfigDataRoot } from "../paths.js";
+import { managedSettingsPath } from "../settings-loader.cjs";
+import { createCliGoalSnapshotReader } from "../cli-goal-source.js";
+import { createProjectGoalConnection } from "../project-goal-connection.js";
+import { formatGoalEvidenceProjection } from "@chainlesschain/session-core/goal-evidence-contract";
+import {
+  collectGoalExtensions,
+  projectGoalExtensionPanel,
+} from "./goal-extensions.js";
+
+export const CLI_GOAL_PANEL_SCHEMA = "chainlesschain.goal-extension-panels.v1";
+export const CLI_GOAL_EXTENSION_HOST = Object.freeze({
+  id: "cli",
+  version: VERSION,
+  capabilities: Object.freeze(["panel:goal.summary"]),
+});
+export const _deps = { collectGoalExtensions, projectGoalExtensionPanel };
+
+function fail(code) {
+  throw new Error(code);
+}
+function digest(record) {
+  return createHash("sha256").update(JSON.stringify(record)).digest("hex");
+}
+/** Explicit user read; all source/plugin revalidation completes before return. */
+export async function readCliGoalExtensionPanels(id, options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const env = Object.freeze({ ...(options.env || process.env) });
+  const root = path.resolve(
+    options.root ||
+      path.join(resolveConfigDataRoot({ cwd, env }).path, "goals"),
+  );
+  const managedSettingsFile = managedSettingsPath({
+    env,
+    managedSettingsFile: options.managedSettingsFile,
+  });
+  const pluginName = options.plugin;
+  const scope = options.scope;
+  if (scope !== undefined && !["user", "project", "local"].includes(scope))
+    fail("CLI_GOAL_INVALID_PLUGIN_SCOPE");
+  if (
+    pluginName !== undefined &&
+    (typeof pluginName !== "string" || !pluginName || pluginName.length > 256)
+  )
+    fail("CLI_GOAL_INVALID_PLUGIN_NAME");
+  const connection =
+    options.connection !== undefined
+      ? createProjectGoalConnection(options.connection)
+      : null;
+  const source = connection
+    ? { storeId: connection.goalRef.storeId }
+    : createCliGoalSnapshotReader(root);
+  if (
+    options.expectedStore !== undefined &&
+    options.expectedStore !== source.storeId
+  )
+    fail("CLI_GOAL_STORE_MISMATCH");
+  const remote = connection ? await connection.read(id) : null;
+  const snapshot = connection ? null : source.read(id);
+  const goal = remote
+    ? { ...remote.goalRef, objective: remote.objective, status: remote.status }
+    : snapshot.goal;
+  const goalRef = Object.freeze({
+    id: goal.id,
+    storeId: goal.storeId,
+    revision: goal.revision,
+    controlGeneration: goal.controlGeneration,
+  });
+  const currentGoal = async () => {
+    if (!connection) return source.revalidate(snapshot);
+    const latest = await connection.read(id);
+    if (
+      latest.objective !== goal.objective ||
+      latest.status !== goal.status ||
+      (connection.evidence &&
+        digest({ risk: latest.risk, receipts: latest.receipts }) !==
+          digest({ risk: remote.risk, receipts: remote.receipts }))
+    )
+      fail("CLI_GOAL_CONNECTION_CHANGED");
+    return {
+      ...latest.goalRef,
+      objective: latest.objective,
+      status: latest.status,
+      ...(connection.evidence
+        ? { risk: latest.risk, receipts: latest.receipts }
+        : {}),
+    };
+  };
+  const hostOptions = Object.freeze({
+    cwd,
+    env,
+    managedSettingsFile,
+    host: connection?.evidence
+      ? Object.freeze({
+          ...CLI_GOAL_EXTENSION_HOST,
+          capabilities: Object.freeze([
+            "panel:goal.summary",
+            "panel:goal.evidence",
+          ]),
+        })
+      : CLI_GOAL_EXTENSION_HOST,
+    async authorize(context) {
+      if (
+        context.operation !== "read-panel" ||
+        context.goalRef.id !== id ||
+        context.goalRef.storeId !== source.storeId ||
+        context.goalRef.revision !== goalRef.revision ||
+        context.goalRef.controlGeneration !== goalRef.controlGeneration
+      )
+        return false;
+      await currentGoal();
+      return true;
+    },
+    async readPanel(context) {
+      if (
+        ![
+          "goal.summary",
+          ...(connection?.evidence ? ["goal.evidence"] : []),
+        ].includes(context.panel.slot) ||
+        context.panel.fields.some(
+          (field) =>
+            ![
+              "objective",
+              "status",
+              ...(connection?.evidence && context.panel.slot === "goal.evidence"
+                ? ["riskSummary", "receiptSummary"]
+                : []),
+            ].includes(field),
+        )
+      )
+        fail("CLI_GOAL_PANEL_FIELDS_UNSUPPORTED");
+      const current = await currentGoal();
+      const objective =
+        current.objective.length > 4096
+          ? `${current.objective.slice(0, 4075)}… [truncated]`
+          : current.objective;
+      return {
+        objective,
+        status: current.status,
+        ...(connection?.evidence && context.panel.slot === "goal.evidence"
+          ? formatGoalEvidenceProjection({
+              risk: current.risk,
+              receipts: current.receipts,
+            })
+          : {}),
+      };
+    },
+  });
+  const selected = (entry) =>
+    (!pluginName || entry.name === pluginName) &&
+    (!scope || entry.scope === scope);
+  const initial = _deps.collectGoalExtensions(hostOptions);
+  const plugins = initial.extensions.filter(selected);
+  const dropped = initial.dropped.filter(
+    (entry) => !entry.name || selected(entry),
+  );
+  if (plugins.length > 32) fail("CLI_GOAL_PANEL_LIMIT_EXCEEDED");
+  let panels = [];
+  for (const plugin of plugins) {
+    const ref = {
+      name: plugin.name,
+      scope: plugin.scope,
+      version: plugin.version,
+    };
+    const projected = [];
+    try {
+      for (const panel of plugin.declaration.panels) {
+        projected.push({
+          plugin: ref,
+          ...(await _deps.projectGoalExtensionPanel(
+            ref,
+            { panelId: panel.id, goalRef },
+            hostOptions,
+          )),
+        });
+      }
+      panels.push(...projected);
+    } catch {
+      dropped.push({
+        name: plugin.name,
+        scope: plugin.scope,
+        reason: "panel_unavailable",
+      });
+    }
+    if (panels.length > 16) fail("CLI_GOAL_PANEL_LIMIT_EXCEEDED");
+  }
+  await currentGoal();
+  const latest = _deps.collectGoalExtensions(hostOptions);
+  panels = panels.filter((panel) => {
+    const before = plugins.find(
+      (plugin) =>
+        plugin.name === panel.plugin.name &&
+        plugin.scope === panel.plugin.scope,
+    );
+    const after = latest.extensions.find(
+      (plugin) =>
+        plugin.name === panel.plugin.name &&
+        plugin.scope === panel.plugin.scope &&
+        plugin.version === panel.plugin.version,
+    );
+    const allowed =
+      after && digest(after.declaration) === digest(before.declaration);
+    if (
+      !allowed &&
+      !dropped.some(
+        (entry) =>
+          entry.name === panel.plugin.name &&
+          entry.scope === panel.plugin.scope,
+      )
+    )
+      dropped.push({
+        name: panel.plugin.name,
+        scope: panel.plugin.scope,
+        reason: "admission_changed",
+      });
+    return allowed;
+  });
+  const result = {
+    schema: CLI_GOAL_PANEL_SCHEMA,
+    ...(connection ? { source: "desktop-project" } : {}),
+    goalRef,
+    snapshot: true,
+    observedAt: new Date().toISOString(),
+    panels,
+    dropped,
+  };
+  if (Buffer.byteLength(JSON.stringify(result), "utf8") > 128 * 1024)
+    fail("CLI_GOAL_PANEL_LIMIT_EXCEEDED");
+  return result;
+}

package/src/lib/plugin-runtime/examples/goal-description-drafter/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "goal-description-drafter",
+  "version": "0.1.0",
+  "description": "Export user-selected description requests for explicit native adoption",
+  "permissions": { "goalExtension": ["proposal:task.description.update"] },
+  "goalExtension": {
+    "apiVersion": "1.0.0",
+    "hosts": {
+      "cli": ">=0.166.104",
+      "vscode": ">=0.37.149",
+      "jetbrains": ">=0.4.166"
+    },
+    "events": [],
+    "panels": [],
+    "proposals": ["task.description.update"]
+  }
+}

package/src/lib/plugin-runtime/examples/goal-evidence-viewer/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "goal-evidence-viewer",
+  "version": "0.1.0",
+  "description": "Read historical risk checks and action-receipt summaries through an explicitly authorized desktop evidence connection",
+  "permissions": { "goalExtension": ["panel:goal.evidence"] },
+  "goalExtension": {
+    "apiVersion": "1.0.0",
+    "hosts": {
+      "cli": ">=0.166.104",
+      "vscode": ">=0.37.149",
+      "jetbrains": ">=0.4.166"
+    },
+    "events": [],
+    "panels": [
+      {
+        "id": "delivery-evidence",
+        "title": "Historical project goal evidence",
+        "slot": "goal.evidence",
+        "fields": ["objective", "status", "riskSummary", "receiptSummary"],
+        "fallback": "text"
+      }
+    ],
+    "proposals": []
+  }
+}