@brainervirus/workit-core 4.0.0 → 6.0.0

package/src/autonomy.ts

@@ -1,37 +1,113 @@
-// Autonomy grants (D4, D15; design §0 #12, §4.2): the per-workspace ceiling on
-// what an agent may deliver without asking. S11 introduces the reader and the
-// one seam every delivery verb consults, `requireGrant(kind)`; S16 adds
-// `workit grant`, the D4 defaults and the legacy `autoApprove` mapping.
+// Autonomy grants (D2, D4, D15; design §0 #12, §4.2): the per-workspace
+// ceiling on what an agent may deliver without asking. Authority is the
+// host's own permission prompt plus these grants; no approval ticket or
+// checkout lease stands behind them.
 //
-// Today (S11):
-// - Grants are read only from the matched workspace entry in the user's
-//   `~/.config/workit/workspaces.json` (`"autonomy": {"push": true, "pr": true,
-//   "merge": false | true | "verified", "release": false}`), never from a repo
-//   file, and nothing here writes them (D15: never raised headless).
-// - An explicit value is honored: `false` denies with `grant_required`, `true`
-//   allows, and `merge: "verified"` allows only with an accepted independent
-//   verdict (S13). `merge: true` is the only way to merge without one.
-// - An absent grant is allowed on the host's own authority (`source:
-//   "host_authority"`): the host permission prompt is the ceiling, and a merge
-//   still needs an accepted verdict. S16 replaces that default with the D4
-//   ceiling `{push: true, pr: true, merge: false, release: false}`.
-// - Grants require an account (design §2.0 Identity): a workspace with any
-//   grant but no `vcs.account` cannot push, open or merge through a forge,
-//   so a personal grant never rides a work credential.
-import { resolveRuntimeWorkspaceVcs } from "./core/workspaces";
-
-export type GrantKind = "push" | "pr" | "merge" | "release";
-const GRANT_KINDS: readonly GrantKind[] = ["push", "pr", "merge", "release"];
-
-/** One grant as configured: `"verified"` means allowed with an accepted verdict. */
+// - Grants live only in the matched workspace entry of the user's
+//   `~/.config/workit/workspaces.json`, where `~` is the OS account's home
+//   (neither $HOME nor config-dir overrides redirect them; see grantsDir):
+//     "autonomy": { "push": true, "pr": true, "merge": false | true | "verified",
+//                   "release": false, "rerun": true }
+//   never in a repo file. `workit grant set` raises only from an interactive
+//   terminal (see verbs/grant.ts). Threat model (D18): this stops an honest
+//   agent from raising its own ceiling by accident, not an adversarial one —
+//   a process that drives a pseudo-terminal or edits the file directly can
+//   still defeat it; the host's permission prompt is the hard boundary.
+// - `release` has no consuming verb yet; it is reserved, not enforced.
+// - Defaults (D4) when a kind is absent: push, pr and rerun are allowed;
+//   merge and release need an explicit grant. The default ceiling is a stack
+//   opened, CI green and independently verified: "verified, ready".
+// - `merge: "verified"` allows a merge only with an accepted independent
+//   verdict (S13); `merge: true` is the only way to merge without one.
+// - A legacy `autoApprove: true | [classes]` maps once to grants (its `merge`
+//   class becomes `merge: "verified"`; `branch`/`commit` are local, dropped).
+// - Explicitly configured grants require an account (design §2.0 Identity):
+//   a workspace with grants but no `vcs.account` cannot push, open or merge
+//   through a forge, so a personal grant never rides a work credential.
+// - Protected-branch pushes stay denied by the git verbs, and the host
+//   permission prompt applies in addition: a host deny always wins.
+import { copyFileSync, existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveConfigDir } from "./core/config";
+import { writeFileAtomic } from "./core/safe-write";
+import {
+  readWorkspacesResult,
+  resolveWorkspaceFrom,
+  validateWorkspacesDocument,
+} from "./core/workspaces";
+
+/**
+ * Grants are read only from the user's real config directory,
+ * `<account home>/.config/workit` (D15; see grantsHome). The WORKFLOW_TOOLKIT_CONFIG(_DIR) and
+ * XDG_CONFIG_HOME overrides that redirect the rest of the config never
+ * redirect grants: an agent could point them at a file it wrote. While an
+ * override points elsewhere, grants resolve to the D4 defaults.
+ */
+const accountHome = (): string => {
+  try {
+    return os.userInfo().homedir;
+  } catch {
+    return os.homedir();
+  }
+};
+
+/**
+ * Where grants are read from: the OS account record's home directory, never
+ * `$HOME` (an agent can set that for one command). Tests swap `resolve`
+ * in-process; nothing outside this process can change it.
+ */
+export const grantsHome = { resolve: accountHome };
+
+export const grantsDir = (): string => path.join(grantsHome.resolve(), ".config", "workit");
+
+/** Why grants fell back to the defaults, or null when the real file is used. */
+export const grantsOverride = (): string | null => {
+  const configured = path.resolve(resolveConfigDir());
+  return configured === path.resolve(grantsDir())
+    ? null
+    : `the config directory is redirected to ${configured} (WORKFLOW_TOOLKIT_CONFIG, WORKFLOW_TOOLKIT_CONFIG_DIR or XDG_CONFIG_HOME); grants are read only from ${path.join(grantsDir(), "workspaces.json")}, so the D4 defaults apply`;
+};
+
+export const GRANT_KINDS = ["push", "pr", "merge", "release", "rerun"] as const;
+export type GrantKind = (typeof GRANT_KINDS)[number];
+
+/** One grant: `"verified"` means allowed with an accepted independent verdict. */
 export type GrantValue = boolean | "verified";
+export type Grants = Record<GrantKind, GrantValue>;
+
+/** The D4 ceiling: deliver up to "verified, ready"; merging and releasing are asked. */
+export const DEFAULT_GRANTS: Readonly<Grants> = Object.freeze({
+  push: true,
+  pr: true,
+  merge: false,
+  release: false,
+  rerun: true,
+});
+
+/**
+ * Where an unnamed request stops (skills read it): `commit` (default) ends at
+ * a local commit; `pr` goes on to push and open the PR. User config only,
+ * same rules as grants: raising commit → pr needs the user at a terminal.
+ */
+export type DefaultEndpoint = "commit" | "pr";
+export const DEFAULT_ENDPOINT: DefaultEndpoint = "commit";
+const endpointOf = (entry: unknown): DefaultEndpoint =>
+  (entry as { defaultEndpoint?: unknown } | null)?.defaultEndpoint === "pr" ? "pr" : "commit";
+
+export type AutonomySource = "autonomy" | "autoApprove" | "default";
 
 export type Autonomy = {
   workspace: string | null;
-  /** Explicitly configured grants; a kind that is absent falls back to host authority. */
-  grants: Partial<Record<GrantKind, GrantValue>>;
-  source: "autonomy" | "host_authority";
+  /** Every kind, with absent ones filled from DEFAULT_GRANTS. */
+  grants: Grants;
+  /** The kinds the user configured explicitly (the rest are defaults). */
+  configured: GrantKind[];
+  source: AutonomySource;
   accountConfigured: boolean;
+  defaultEndpoint: DefaultEndpoint;
+  /** Set when the grants file was not read (see grantsOverride). */
+  note?: string;
 };
 
 export type GrantDecision =
@@ -39,7 +115,7 @@ export type GrantDecision =
       allowed: true;
       kind: GrantKind;
       /** Where the permission came from. */
-      source: "autonomy" | "host_authority";
+      source: AutonomySource;
       /** A merge must also have an accepted independent verdict (S13). */
       requireVerdict: boolean;
       workspace: string | null;
@@ -53,29 +129,82 @@ export type GrantDecision =
       workspace: string | null;
     };
 
+export const isGrantKind = (value: unknown): value is GrantKind =>
+  typeof value === "string" && (GRANT_KINDS as readonly string[]).includes(value);
+
 const isGrantValue = (value: unknown): value is GrantValue =>
   value === true || value === false || value === "verified";
 
-/** The grants for the workspace `cwd` belongs to (read-only). */
-export function resolveAutonomy(cwd: string): Autonomy {
-  const workspace = resolveRuntimeWorkspaceVcs(cwd);
-  const raw = (workspace as { autonomy?: unknown } | null)?.autonomy;
-  const grants: Autonomy["grants"] = {};
-  if (raw && typeof raw === "object" && !Array.isArray(raw))
+/** `verified` is meaningful only for merge; elsewhere it means allowed. */
+const normalized = (kind: GrantKind, value: GrantValue): GrantValue =>
+  value === "verified" && kind !== "merge" ? true : value;
+
+/** Legacy `autoApprove` (≤4.x standing approvals) → grants, mapped once on read. */
+const fromAutoApprove = (value: unknown): Partial<Grants> | null => {
+  // A standing merge approval maps to merge "verified": an accepted
+  // independent verdict is still required (S16 review L1).
+  if (value === true) return { push: true, pr: true, merge: "verified" };
+  if (!Array.isArray(value)) return null;
+  const grants: Partial<Grants> = {};
+  for (const item of value as unknown[])
+    if (item === "push" || item === "pr") grants[item] = true;
+    else if (item === "merge") grants.merge = "verified";
+  return Object.keys(grants).length > 0 ? grants : null;
+};
+
+/** The explicit grants of one workspace entry, before defaults. */
+export function configuredGrants(entry: unknown): {
+  grants: Partial<Grants>;
+  source: AutonomySource;
+} {
+  const record = (entry ?? {}) as { autonomy?: unknown; autoApprove?: unknown };
+  const raw = record.autonomy;
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    const grants: Partial<Grants> = {};
     for (const kind of GRANT_KINDS) {
       const value = (raw as Record<string, unknown>)[kind];
-      if (isGrantValue(value)) grants[kind] = value;
+      if (isGrantValue(value)) grants[kind] = normalized(kind, value);
     }
+    return { grants, source: "autonomy" };
+  }
+  const legacy = fromAutoApprove(record.autoApprove);
+  return legacy ? { grants: legacy, source: "autoApprove" } : { grants: {}, source: "default" };
+}
+
+/** The grants for the workspace `cwd` belongs to (read-only). */
+export function resolveAutonomy(cwd: string): Autonomy {
+  const override = grantsOverride();
+  if (override)
+    return {
+      workspace: null,
+      grants: { ...DEFAULT_GRANTS },
+      configured: [],
+      source: "default",
+      accountConfigured: false,
+      defaultEndpoint: DEFAULT_ENDPOINT,
+      note: override,
+    };
+  const workspace = resolveWorkspaceFrom(
+    cwd,
+    grantsDir(),
+    process.env.WORKFLOW_WORKSPACE_NAME?.trim() || undefined,
+  );
+  const { grants, source } = configuredGrants(workspace);
   return {
     workspace: workspace?.name ?? null,
-    grants,
-    source: Object.keys(grants).length > 0 ? "autonomy" : "host_authority",
+    grants: { ...DEFAULT_GRANTS, ...grants },
+    configured: GRANT_KINDS.filter((kind) => grants[kind] !== undefined),
+    source,
     accountConfigured: Boolean(workspace?.vcs?.account),
+    defaultEndpoint: endpointOf(workspace),
   };
 }
 
-const grantHint = (workspace: string | null, kind: GrantKind): string =>
-  `ask the user to set "autonomy": {"${kind}": ${kind === "merge" ? '"verified"' : "true"}} for workspace "${workspace ?? "?"}" in ~/.config/workit/workspaces.json (S16: workit grant set ${workspace ?? "<workspace>"} ${kind}=${kind === "merge" ? "verified" : "true"})`;
+const suggested = (kind: GrantKind): string => (kind === "merge" ? "verified" : "true");
+
+/** The one way to clear a missing grant: the user raises it from a terminal. */
+export const grantHint = (workspace: string | null, kind: GrantKind): string =>
+  `ask the user to run, in their own terminal: workit grant set ${workspace ?? "<workspace>"} ${kind}=${suggested(kind)}`;
 
 /**
  * The seam every delivery verb consults before an external effect. `forge`
@@ -102,17 +231,21 @@ export function requireGrant(
   }
   const { workspace } = autonomy;
   const value = autonomy.grants[kind];
+  const configured = autonomy.configured.includes(kind);
   if (value === false)
     return {
       allowed: false,
       kind,
       reason: "grant_required",
-      error: `grant_required: ${kind} is not granted for workspace "${workspace ?? "?"}"`,
-      unblock: grantHint(workspace, kind),
+      error: `grant_required: ${kind} is not granted for ${workspace ? `workspace "${workspace}"` : "this checkout (no workspace matches it)"}${configured ? "" : " (the default ceiling stops at verified, ready)"}${autonomy.note ? `; ${autonomy.note}` : ""}`,
+      unblock: workspace
+        ? grantHint(workspace, kind)
+        : "ask the user to add a workspace for this checkout (workit init → Workspaces), then: workit grant set <workspace> " +
+          `${kind}=${suggested(kind)}`,
       workspace,
     };
   if (
-    autonomy.source === "autonomy" &&
+    autonomy.configured.length > 0 &&
     !autonomy.accountConfigured &&
     options.forge !== false &&
     kind !== "release"
@@ -128,8 +261,140 @@ export function requireGrant(
   return {
     allowed: true,
     kind,
-    source: value === undefined ? "host_authority" : "autonomy",
+    source: configured ? autonomy.source : "default",
     requireVerdict: kind === "merge" && value !== true,
     workspace,
   };
 }
+
+/** Whether `next` grants more than `current` (false < "verified" < true). */
+export const raises = (kind: GrantKind, current: GrantValue, next: GrantValue): boolean => {
+  const rank = (value: GrantValue) => (value === true ? 2 : value === "verified" ? 1 : 0);
+  return rank(normalized(kind, next)) > rank(normalized(kind, current));
+};
+
+export type GrantWrite =
+  | {
+      ok: true;
+      path: string;
+      backup: string | null;
+      workspace: string;
+      grants: Grants;
+      configured: GrantKind[];
+      defaultEndpoint: DefaultEndpoint;
+    }
+  | { ok: false; code: "not_found" | "invalid_input" | "failed"; error: string };
+
+/**
+ * Set (`value`) or unset (`undefined`) grants of a named workspace in the
+ * user's workspaces.json. The caller decides whether raising is allowed (an
+ * interactive terminal only); this only writes, atomically, after copying
+ * the previous file to `workspaces.json.bak`. A legacy `autoApprove` is
+ * folded into `autonomy` on the first write and removed.
+ */
+export function writeGrants(
+  workspaceName: string,
+  changes: readonly { kind: GrantKind; value: GrantValue | undefined }[],
+  dir: string = grantsDir(),
+  /** A new default endpoint; `null` removes it (back to `commit`). */
+  endpoint?: DefaultEndpoint | null,
+): GrantWrite {
+  const current = readWorkspacesResult(dir);
+  if (current.status === "missing")
+    return { ok: false, code: "not_found", error: `${current.path} does not exist` };
+  if (current.status !== "valid" || !current.document)
+    return { ok: false, code: "invalid_input", error: current.error ?? "invalid workspaces.json" };
+  const document = structuredClone(current.document) as {
+    workspaces?: Record<string, unknown>[];
+  };
+  const entry = document.workspaces?.find((item) => item.name === workspaceName);
+  if (!entry)
+    return {
+      ok: false,
+      code: "not_found",
+      error: `no workspace named "${workspaceName}" in ${current.path}`,
+    };
+  const { grants } = configuredGrants(entry);
+  for (const { kind, value } of changes)
+    if (value === undefined) delete grants[kind];
+    else grants[kind] = normalized(kind, value);
+  // Keys this version does not know stay as they are (S16 review L6).
+  const unknown = Object.fromEntries(
+    Object.entries(
+      entry.autonomy && typeof entry.autonomy === "object" && !Array.isArray(entry.autonomy)
+        ? (entry.autonomy as Record<string, unknown>)
+        : {},
+    ).filter(([key]) => !isGrantKind(key)),
+  );
+  delete entry.autoApprove;
+  if (endpoint === null || endpoint === DEFAULT_ENDPOINT) delete entry.defaultEndpoint;
+  else if (endpoint) entry.defaultEndpoint = endpoint;
+  const autonomy = {
+    ...unknown,
+    ...Object.fromEntries(
+      GRANT_KINDS.filter((item) => grants[item] !== undefined).map((item) => [item, grants[item]]),
+    ),
+  };
+  if (Object.keys(autonomy).length === 0) delete entry.autonomy;
+  else entry.autonomy = autonomy;
+  const validated = validateWorkspacesDocument(document, current.path);
+  if (validated.status !== "valid")
+    return { ok: false, code: "invalid_input", error: validated.error ?? "invalid result" };
+  // Re-read just before writing: a concurrent edit wins over this one.
+  const latest = readWorkspacesResult(dir);
+  if (latest.revision !== current.revision)
+    return { ok: false, code: "failed", error: `${current.path} changed; retry` };
+  let backup: string | null = null;
+  try {
+    if (existsSync(current.path)) {
+      backup = `${current.path}.bak`;
+      copyFileSync(current.path, backup);
+    }
+    writeFileAtomic(current.path, `${JSON.stringify(document, null, 2)}\n`);
+  } catch (error) {
+    return {
+      ok: false,
+      code: "failed",
+      error: `failed to write ${current.path}: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+  return {
+    ok: true,
+    path: current.path,
+    backup,
+    workspace: workspaceName,
+    grants: { ...DEFAULT_GRANTS, ...grants },
+    configured: GRANT_KINDS.filter((kind) => grants[kind] !== undefined),
+    defaultEndpoint: endpointOf(entry),
+  };
+}
+
+/** Every workspace's grants, for `workit grant show --all`. */
+export function listGrants(dir: string = grantsDir()): {
+  path: string;
+  workspaces: {
+    name: string;
+    glob: string;
+    grants: Grants;
+    configured: GrantKind[];
+    defaultEndpoint: DefaultEndpoint;
+  }[];
+  error?: string;
+} {
+  const current = readWorkspacesResult(dir);
+  if (current.status === "malformed" || current.status === "invalid")
+    return { path: current.path, workspaces: [], error: current.error };
+  return {
+    path: current.path,
+    workspaces: current.entries.map((entry) => {
+      const { grants } = configuredGrants(entry);
+      return {
+        name: entry.name,
+        glob: entry.glob,
+        grants: { ...DEFAULT_GRANTS, ...grants },
+        configured: GRANT_KINDS.filter((kind) => grants[kind] !== undefined),
+        defaultEndpoint: endpointOf(entry),
+      };
+    }),
+  };
+}

package/src/core/context-read.ts

@@ -0,0 +1,144 @@
+// Read-only repository and provider context (`workit_context` on OpenCode,
+// Pi and MCP). A read needs no grant: it changes nothing locally or remotely.
+import * as z from "zod";
+import {
+  changelogContext,
+  docsRefreshContext,
+  isSafeContextRange,
+  prReadyContext,
+  releaseNotesContext,
+} from "./repo-context";
+import { gitContext } from "./git";
+import { fetchGitHubIssueBody, fetchGitLabIssueBody } from "./tracker-issues";
+import { context as youTrackContext, fetchYouTrackIssueBody } from "./youtrack";
+import { failure, success, type Result } from "./task-contract";
+
+export const contextReadSchema = z
+  .object({
+    kind: z.enum([
+      "git",
+      "pr",
+      "youtrack",
+      "github_issue",
+      "gitlab_issue",
+      "changelog",
+      "release",
+      "affected",
+    ]),
+    range: z.string().optional(),
+    issueId: z.string().optional(),
+    issueUrl: z.string().optional(),
+    issueRef: z.string().optional(),
+    mode: z.string().optional(),
+    specPath: z.string().optional(),
+    planPath: z.string().optional(),
+    cwd: z.string().min(1).optional(),
+  })
+  .strict();
+export type ContextReadPayload = z.infer<typeof contextReadSchema>;
+
+/** The tool input schema hosts register for `workit_context`. */
+export const contextReadJsonSchema = (): Record<string, unknown> => {
+  const { $schema: _schema, ...schema } = z.toJSONSchema(contextReadSchema, {
+    target: "draft-2020-12",
+  }) as Record<string, unknown>;
+  return schema;
+};
+
+export const parseContextRead = (value: unknown): Result<ContextReadPayload> => {
+  const parsed = contextReadSchema.safeParse(value);
+  return parsed.success
+    ? success(null, null, parsed.data)
+    : failure("invalid_input", "context payload is invalid", {
+        fields: parsed.error.issues.map((issue) => ({
+          path: issue.path.join("."),
+          reason: issue.message,
+        })),
+      });
+};
+
+/** Read one fixed repository/provider context without approval or mutation. */
+export const readExternalContext = async (
+  root: string,
+  payload: ContextReadPayload,
+): Promise<Result<unknown>> => {
+  if (payload.range !== undefined && !isSafeContextRange(payload.range))
+    return failure("invalid_input", "revision range is invalid", {
+      fields: [{ path: "range", reason: "option-like or control characters are not allowed" }],
+    });
+  const render = (result: { stdout: string; stderr: string; exitCode: number; cwd: string }) =>
+    result.exitCode === 0
+      ? success(null, null, { kind: payload.kind, context: result.stdout })
+      : failure("capability_unavailable", "requested context is unavailable", {
+          capability: payload.kind,
+        });
+  switch (payload.kind) {
+    case "git": {
+      const context = gitContext(root);
+      return typeof context.exitCode === "number" && context.exitCode !== 0
+        ? failure("capability_unavailable", "Git context is unavailable", { capability: "git" })
+        : success(null, null, { kind: payload.kind, context });
+    }
+    case "pr":
+      return render(prReadyContext(root, payload.range));
+    case "changelog":
+      return render(changelogContext(root, payload.range));
+    case "release":
+      return render(releaseNotesContext(root, payload.range ?? "HEAD~1...HEAD"));
+    case "affected":
+      return render(docsRefreshContext(root, payload.range));
+    case "youtrack": {
+      const value = youTrackContext({
+        workspace_root: root,
+        ...(payload.specPath ? { spec_path: payload.specPath } : {}),
+        ...(payload.planPath ? { plan_path: payload.planPath } : {}),
+        ...(payload.issueId ? { issue_id: payload.issueId } : {}),
+        ...(payload.issueUrl ? { issue_url: payload.issueUrl } : {}),
+        ...(payload.issueRef ? { issue_ref: payload.issueRef } : {}),
+        ...(payload.mode ? { mode: payload.mode } : {}),
+      });
+      if (value && typeof value === "object" && "error" in value)
+        return failure("capability_unavailable", "YouTrack context is unavailable", {
+          capability: "youtrack",
+        });
+      if (value.requiresMeetingChoice || !value.issueId)
+        return success(null, null, { kind: payload.kind, context: value });
+      const body = await fetchYouTrackIssueBody(value.issueId);
+      if ("error" in body && body.kind === "request")
+        return failure("capability_unavailable", "YouTrack issue body is unavailable", {
+          capability: "youtrack",
+        });
+      return success(null, null, {
+        kind: payload.kind,
+        context: {
+          ...value,
+          ...("data" in body
+            ? { issueBody: body.data }
+            : { issueBody: null, issueBodyError: body.error }),
+        },
+      });
+    }
+    case "github_issue": {
+      const ref = payload.issueId ?? payload.issueUrl ?? payload.issueRef;
+      if (!ref)
+        return failure("invalid_input", "github_issue needs issueId, issueUrl, or issueRef");
+      const body = await fetchGitHubIssueBody(ref, root);
+      if ("error" in body)
+        return failure("capability_unavailable", `GitHub issue is unavailable: ${body.error}`, {
+          capability: "github_issue",
+        });
+      return success(null, null, { kind: payload.kind, context: { issueBody: body.data } });
+    }
+    case "gitlab_issue": {
+      const ref = payload.issueId ?? payload.issueUrl ?? payload.issueRef;
+      if (!ref)
+        return failure("invalid_input", "gitlab_issue needs issueId, issueUrl, or issueRef");
+      const body = await fetchGitLabIssueBody(ref, root);
+      if ("error" in body)
+        return failure("capability_unavailable", `GitLab issue is unavailable: ${body.error}`, {
+          capability: "gitlab_issue",
+        });
+      return success(null, null, { kind: payload.kind, context: { issueBody: body.data } });
+    }
+  }
+};