@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/src/cli/context.ts

@@ -0,0 +1,299 @@
+/**
+ * What every command of `asturiu-v0-tenant` shares: the run's context, failures the person can act on, the Tenant
+ * API through the SDK's own calls, and the repository's local state. The Tenant key is read from the environment and
+ * never printed (ADR-074 §14).
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import * as sdk from "../index.js";
+import { TenantApiError, parseTenantKey } from "../definition-set.js";
+import { type Json, type Sources, folderSources } from "./sources.js";
+import { type Terminal, plain } from "./terminal.js";
+
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export type Env = Record<string, string | undefined>;
+
+/** What a repository may set in `asturiu.config.mjs` (or `asturiu/config.mjs`); every key is optional. */
+export interface Config {
+  /** The application's name in headings and bundled reports (default: the Tenant's slug). */
+  product?: string;
+  /** Where the Definition set, branding and portal options live (default: `asturiu/`). `kit` is the SDK, for configurations that call it. */
+  sources?: Sources | ((o: { root: string; kit: typeof sdk }) => Sources);
+  /** The Tenant API when ASTURIU_TENANT_API_URL is not set. */
+  tenantApiUrl?: string;
+  /** Where `changesets pull` puts documents (default: `asturiu/changesets`). */
+  changesetsDir?: string;
+  /** The file with the Asturiu section (default: `AGENTS.md`). */
+  agentsFile?: string;
+  /** The changesets the repository records as done (default: up to the section's `changeset=`). */
+  recorded?: (root: string) => Set<number>;
+  /** The area of a finding that names none (default: `application`). */
+  feedbackArea?: string;
+  /** More patterns a report must not hold (a session cookie's name). */
+  secrets?: RegExp[];
+  /** How the person runs this, for the hints (default: guessed from the package manager). */
+  command?: string;
+  /** Set by `loadConfig`: where the configuration was read. */
+  file?: string;
+}
+
+export interface Ctx {
+  root: string;
+  t: Terminal;
+  json: boolean;
+  flags: Record<string, string | true>;
+  env: Env;
+  config: Config;
+  /** The command prefix for hints: `pnpm asturiu`, `npm run asturiu --`, `npx --no-install asturiu-v0-tenant`. */
+  cmd: string;
+  cfg: { key: string; baseUrl: string } | null;
+  key: string | null;
+  baseUrl: string | null;
+  fetch: FetchLike | undefined;
+  keyExpires: string | null;
+  product: string;
+  _sources: Sources | null;
+  /** The exit code: 0 done, 1 failed or refused, 2 not understood, 3 done here but not reported to the Engine. */
+  exit?: number;
+}
+
+/** The exit codes (ADR-074 §5). */
+export const EXIT = { done: 0, failed: 1, misunderstood: 2, notReported: 3 } as const;
+
+/** A failure the person can act on: a title, what happened, what to do. */
+export class Fail extends Error {
+  hint?: string;
+  lines: string[];
+  code: number;
+  data?: Json;
+  constructor(message: string, o: { hint?: string; lines?: string[]; code?: number; data?: Json } = {}) {
+    super(message);
+    this.hint = o.hint;
+    this.lines = o.lines ?? [];
+    this.code = o.code ?? EXIT.failed;
+    this.data = o.data;
+  }
+}
+
+/** The repository's configuration: `asturiu.config.mjs` at its root, else `asturiu/config.mjs`, else none. */
+export async function loadConfig(root: string): Promise<Config> {
+  for (const name of ["asturiu.config.mjs", path.join("asturiu", "config.mjs")]) {
+    const file = path.join(root, name);
+    if (!existsSync(file)) continue;
+    const mod = (await import(pathToFileURL(file).href)) as { default?: Config } & Config;
+    return { ...(mod.default ?? mod), file: name };
+  }
+  return {};
+}
+
+/** How the person runs this, for the hints: the package script when there is one, else `npx --no-install asturiu-v0-tenant`. */
+export function commandPrefix(env: Env, fallback: string): string {
+  const script = env.npm_lifecycle_event;
+  const ua = env.npm_config_user_agent ?? "";
+  if (!script || script === "npx") return fallback;
+  if (ua.startsWith("pnpm")) return `pnpm ${script}`;
+  if (ua.startsWith("yarn")) return `yarn ${script}`;
+  if (ua.startsWith("bun")) return `bun run ${script}`;
+  return `npm run ${script} --`;
+}
+
+/** The Tenant's slug, out of the key's first part (`atk.<slug>.…`): not a secret. */
+export function slugOf(key: string | null): string | null {
+  if (!key) return null;
+  try {
+    return parseTenantKey(key).slug;
+  } catch {
+    return null;
+  }
+}
+
+/** The key's id, out of its second part: not a secret either. */
+export function keyIdOf(key: string | null): string | null {
+  if (!key) return null;
+  try {
+    return parseTenantKey(key).kid;
+  } catch {
+    return null;
+  }
+}
+
+// ================================================================== the Tenant API, through the SDK
+
+export type CallFailure = { ok: false; why: "no-key" | "no-url" | "no-route" | "network" | "refused"; status: number; network: string; message: string; type: string | null };
+export type CallResult<T> = { ok: true; value: T; status: number; network: string } | CallFailure;
+
+/**
+ * One SDK call, with what the network answered: its HTTP status, or why it could not reach the Tenant API. A
+ * `TenantApiError` carries the status itself; the calls that never throw (`applyDefinitions` and the like) are read
+ * through the status the wrapped `fetch` saw.
+ */
+export async function call<T>(ctx: Ctx, fn: (fetch: FetchLike, cfg: { key: string; baseUrl: string }) => Promise<T>): Promise<CallResult<T>> {
+  if (!ctx.key) return { ok: false, why: "no-key", status: 0, network: "", message: "ASTURIU_TENANT_KEY is not set", type: null };
+  if (!ctx.cfg) return { ok: false, why: "no-url", status: 0, network: "", message: "ASTURIU_TENANT_API_URL is not set", type: null };
+  const seen = { status: 0, network: "" };
+  const cfg = ctx.cfg;
+  const tracked: FetchLike = async (input, init) => {
+    try {
+      const res = await (ctx.fetch ?? ((i: string, n?: RequestInit) => globalThis.fetch(i, n)))(input, init);
+      seen.status = res.status;
+      const expires = res.headers.get("asturiu-key-expires");
+      if (expires) ctx.keyExpires = expires;
+      return res;
+    } catch (err) {
+      seen.network = unreachable(err, cfg.baseUrl);
+      throw err;
+    }
+  };
+  try {
+    return { ok: true, value: await fn(tracked, cfg), ...seen };
+  } catch (err) {
+    const status = err instanceof TenantApiError ? err.status : seen.status;
+    const message = seen.network || plain(err instanceof Error ? err.message : String(err));
+    const why = seen.network ? "network" : status === 404 ? "no-route" : "refused";
+    return { ok: false, why, status, network: seen.network, message, type: err instanceof TenantApiError ? err.type : null };
+  }
+}
+
+/** Why the Tenant API could not be reached, in words. */
+export function unreachable(err: unknown, baseUrl: string): string {
+  const cause = (err as { cause?: { code?: string; message?: string } })?.cause;
+  const code = cause?.code ?? "";
+  const words: Record<string, string> = {
+    ECONNREFUSED: "nothing answers there",
+    ENOTFOUND: "the host is unknown",
+    EAI_AGAIN: "the host could not be looked up",
+    ETIMEDOUT: "it did not answer in time",
+    UND_ERR_CONNECT_TIMEOUT: "it did not answer in time",
+    ECONNRESET: "the connection was cut",
+    EPERM: "the connection was not permitted here (a sandbox?)",
+    EHOSTUNREACH: "the host cannot be reached",
+    CERT_HAS_EXPIRED: "its certificate has expired",
+    DEPTH_ZERO_SELF_SIGNED_CERT: "its certificate is self-signed",
+    UNABLE_TO_VERIFY_LEAF_SIGNATURE: "its certificate could not be verified",
+  };
+  return `could not reach the Tenant API at ${hostOf(baseUrl)}: ${words[code] ?? plain(cause?.message ?? (err instanceof Error ? err.message : String(err)))}`;
+}
+
+export const hostOf = (url: string | null | undefined): string => {
+  if (!url) return "—";
+  try {
+    return new URL(url).host;
+  } catch {
+    return url;
+  }
+};
+
+/** A failed read in a few words, for a status line. */
+export function readFailure(r: { why: string; message: string; status: number }, scope?: string): string {
+  if (r.why === "no-key") return "not read: ASTURIU_TENANT_KEY is not set";
+  if (r.why === "no-url") return "not read: ASTURIU_TENANT_API_URL is not set";
+  if (r.why === "no-route") return scope ? `not read: the key lacks the scope “${scope}”, or the Engine has no such route` : "not read: the Engine has no such route";
+  if (r.status === 401) return "not read: the Tenant API refused the key (revoked, expired, or for another Tenant)";
+  return `not read: ${r.message}`;
+}
+
+/** The repository's sources, made once. */
+export function sources(ctx: Ctx): Sources {
+  if (!ctx._sources) {
+    const s = ctx.config.sources;
+    ctx._sources = typeof s === "function" ? s({ root: ctx.root, kit: sdk }) : (s ?? folderSources({ root: ctx.root }));
+  }
+  return ctx._sources;
+}
+
+/** Fails when no key or address is set: for commands that cannot do anything without. */
+export function needTenantApi(ctx: Ctx, what: string): void {
+  if (!ctx.key) throw new Fail(`ASTURIU_TENANT_KEY is not set: ${what}`, { lines: ["The Tenant key is made in the Admin UI (your Tenant › Tenant keys) with the scopes the repository needs. Put it in the server's environment, or in .env, as ASTURIU_TENANT_KEY. Never paste it into a chat, a file under version control or a report."], hint: `${ctx.cmd} doctor checks the whole set-up` });
+  if (!ctx.cfg) throw new Fail(`ASTURIU_TENANT_API_URL is not set: ${what}`, { lines: ["It is the Tenant API's address, given with your Tenant."] });
+}
+
+/** One JSON document on stdout. */
+export function emit(ctx: Ctx, data: unknown): void {
+  ctx.t.out(JSON.stringify(data, null, 2));
+}
+
+// ================================================================== local state
+
+export function places(ctx: Ctx) {
+  return {
+    state: path.join(ctx.root, "asturiu", ".state.json"),
+    queue: path.join(ctx.root, "asturiu", "feedback", "queue"),
+    sent: path.join(ctx.root, "asturiu", "feedback", "sent"),
+    offline: path.join(ctx.root, "asturiu-feedback"),
+    changesets: path.join(ctx.root, ctx.config.changesetsDir ?? path.join("asturiu", "changesets")),
+    agents: path.join(ctx.root, ctx.config.agentsFile ?? "AGENTS.md"),
+  };
+}
+
+export const rel = (ctx: Ctx, file: string): string => path.relative(ctx.root, file) || ".";
+
+export function readState(ctx: Ctx): Json {
+  try {
+    return JSON.parse(readFileSync(places(ctx).state, "utf8")) as Json;
+  } catch {
+    return {};
+  }
+}
+
+export function writeState(ctx: Ctx, patch: Json): void {
+  const file = places(ctx).state;
+  mkdirSync(path.dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ ...readState(ctx), ...patch }, null, 2)}\n`);
+}
+
+/** The Engine version and changeset the Asturiu section in AGENTS.md was written for. */
+export function agentsSection(ctx: Ctx): { engine: string; changeset: number } | null {
+  try {
+    const m = /<!-- asturiu:begin engine=(\S+) changeset=(\d+) -->/.exec(readFileSync(places(ctx).agents, "utf8"));
+    return m ? { engine: m[1], changeset: Number(m[2]) } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The changesets the repository records as done. */
+export function recorded(ctx: Ctx): Set<number> {
+  if (ctx.config.recorded) return ctx.config.recorded(ctx.root);
+  const upTo = agentsSection(ctx)?.changeset ?? 0;
+  return new Set(Array.from({ length: upTo }, (_, i) => i + 1));
+}
+
+export function pulledDocuments(ctx: Ctx): Set<string> {
+  const dir = places(ctx).changesets;
+  return new Set(existsSync(dir) ? readdirSync(dir) : []);
+}
+
+/** Whether git ignores a path: true, false, or null outside a repository. */
+export function gitIgnores(ctx: Ctx, file: string): boolean | null {
+  const r = spawnSync("git", ["check-ignore", "-q", rel(ctx, file)], { cwd: ctx.root, stdio: "ignore" });
+  if (r.error || (r.status !== 0 && r.status !== 1)) return null;
+  return r.status === 0;
+}
+
+// ================================================================== secrets
+
+/** Text that looks like a secret: the Tenant key, a token, a session, a password. Reports and notes never carry one. */
+export function secretIn(ctx: Pick<Ctx, "key" | "config">, text: string): string | null {
+  if (ctx.key && text.includes(ctx.key)) return "the Tenant key";
+  if (/\batk\.[a-z0-9-]+\.[0-9a-f]{8,}\./i.test(text)) return "a Tenant key";
+  if (/-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(text)) return "a private key";
+  if (/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\./.test(text)) return "a token";
+  if (/\b(authorization:\s*(bearer|asturiu-assertion)\s+\S{12,}|x-asturiu-session:\s*\S{12,})/i.test(text)) return "a credential header";
+  if (/\b[a-z0-9_]*session=[A-Za-z0-9._~%-]{16,}/i.test(text)) return "a session identifier";
+  if (/\b(app_password|client_secret|password)\s*[:=]\s*\S{6,}/i.test(text)) return "a password or client secret";
+  for (const re of ctx.config.secrets ?? []) if (re.test(text)) return "a secret this repository names";
+  return null;
+}
+
+/** Fails when the text holds a secret: nothing is sent. */
+export function refuseSecrets(ctx: Ctx, ...texts: (string | undefined)[]): void {
+  for (const text of texts) {
+    const secret = text ? secretIn(ctx, text) : null;
+    if (secret) throw new Fail(`The text looks like it holds ${secret}. Nothing was sent.`);
+  }
+}
+
+/** A flag's string value. */
+export const str = (v: string | true | undefined): string | undefined => (typeof v === "string" ? v : undefined);

package/src/cli/engine.ts

@@ -0,0 +1,112 @@
+/**
+ * The Engine as the Tenant API tells it, the SDK versions it serves (ADR-074 §4), and its changesets with this
+ * Tenant's tickets. The SDK carries no changesets (§9): without the Tenant API the list is not known, and every
+ * command says so instead of guessing.
+ */
+import type { ChangesetEntry, TenantChangeset } from "../changesets.js";
+import { readChangesets, readEngine } from "../definition-set.js";
+import { SDK_VERSION } from "../version.js";
+import { type Ctx, call, readFailure } from "./context.js";
+import type { Terminal } from "./terminal.js";
+
+export type Changeset = ChangesetEntry & Partial<TenantChangeset>;
+
+export interface EngineState {
+  live: boolean;
+  version: string | null;
+  released_at: string | null;
+  latest: number | null;
+  site: { docs: string | null; changesets: string | null };
+  sdk: SdkFit;
+  reason: string | null;
+}
+
+/** How the installed SDK stands with the Engine: `minimum` and `built_with` from `GET /tenant/v0/engine`. */
+export interface SdkFit {
+  installed: string;
+  built_with: string | null;
+  minimum: string | null;
+  /** `served`: at or above the minimum; `below-minimum`: the Engine no longer serves it without a break; `unknown`: the Engine did not say. */
+  fit: "served" | "below-minimum" | "unknown";
+  /** Whether the Engine was built with a newer SDK than the one installed. */
+  newer_available: boolean;
+  /** Whether the installed SDK is newer than the Engine knows: calls it adds may answer 404. */
+  ahead_of_engine: boolean;
+}
+
+/** Semantic versions compared by their numbers; a pre-release comes before its release. */
+export function compareVersions(a: string, b: string): number {
+  const parse = (v: string) => {
+    const [main, pre] = v.split("-", 2);
+    return { n: main.split(".").map((x) => Number(x) || 0), pre: pre ?? null };
+  };
+  const x = parse(a);
+  const y = parse(b);
+  for (let i = 0; i < 3; i++) if ((x.n[i] ?? 0) !== (y.n[i] ?? 0)) return (x.n[i] ?? 0) - (y.n[i] ?? 0);
+  if (x.pre === y.pre) return 0;
+  if (x.pre === null) return 1;
+  if (y.pre === null) return -1;
+  return x.pre < y.pre ? -1 : 1;
+}
+
+export function sdkFit(sdk: { built_with: string; minimum: string } | null | undefined, installed = SDK_VERSION): SdkFit {
+  if (!sdk) return { installed, built_with: null, minimum: null, fit: "unknown", newer_available: false, ahead_of_engine: false };
+  return {
+    installed,
+    built_with: sdk.built_with,
+    minimum: sdk.minimum,
+    fit: compareVersions(installed, sdk.minimum) >= 0 ? "served" : "below-minimum",
+    newer_available: compareVersions(installed, sdk.built_with) < 0,
+    ahead_of_engine: compareVersions(installed, sdk.built_with) > 0,
+  };
+}
+
+export async function engineInfo(ctx: Ctx): Promise<EngineState> {
+  const r = await call(ctx, (fetch, cfg) => readEngine({ ...cfg, fetch }));
+  if (r.ok) return { live: true, version: r.value.version, released_at: r.value.released_at, latest: r.value.latest_changeset, site: r.value.site, sdk: sdkFit(r.value.sdk), reason: null };
+  return { live: false, version: null, released_at: null, latest: null, site: { docs: null, changesets: null }, sdk: sdkFit(null), reason: readFailure(r) };
+}
+
+/** The changesets after `since`, with the Tenant's ticket and status, when the Tenant API answers. */
+export async function changesetList(ctx: Ctx, since: number): Promise<{ live: boolean; latest: number | null; list: Changeset[]; reason: string | null }> {
+  const r = await call(ctx, (fetch, cfg) => readChangesets({ ...cfg, since, fetch }));
+  if (r.ok) return { live: true, latest: r.value.latest, list: r.value.changesets, reason: null };
+  return { live: false, latest: null, list: [], reason: readFailure(r) };
+}
+
+export const CLOSED = new Set(["resolved", "canceled"]);
+export const isOpen = (c: Changeset): boolean => Boolean(c.ticket && c.status && !CLOSED.has(c.status));
+
+/** Open changesets in the order AGENTS.md asks for: the earliest deadline first, then the oldest. */
+export function byUrgency(a: Changeset, b: Changeset): number {
+  if (a.deadline && b.deadline) return a.deadline.localeCompare(b.deadline) || a.number - b.number;
+  if (a.deadline) return -1;
+  if (b.deadline) return 1;
+  return a.number - b.number;
+}
+
+/** How each status looks: its words, its colour, its symbol. */
+export const LOOK: Record<string, [string, "blue" | "cyan" | "yellow" | "magenta" | "green" | "gray", keyof Terminal["sym"]]> = {
+  new: ["new", "blue", "info"],
+  acknowledged: ["acknowledged", "cyan", "open"],
+  in_progress: ["in progress", "yellow", "half"],
+  waiting: ["waiting for you", "yellow", "warn"],
+  on_hold: ["on hold", "magenta", "pause"],
+  resolved: ["resolved", "green", "ok"],
+  canceled: ["canceled", "gray", "cross"],
+  draft: ["draft", "gray", "open"],
+  scheduled: ["scheduled", "cyan", "half"],
+  published: ["published", "green", "ok"],
+  expired: ["expired", "gray", "dash"],
+  withdrawn: ["withdrawn", "gray", "cross"],
+  "nothing asked": ["nothing asked", "gray", "dash"],
+  "no ticket": ["no ticket", "gray", "dash"],
+};
+
+/** A status as text, and painted. */
+export function pill(t: Terminal, key: string): { text: string; painted: string } {
+  const look = LOOK[key];
+  if (!look) return { text: key || "—", painted: t.paint.gray(key || "—") };
+  const text = `${t.sym[look[2]]} ${look[0]}`;
+  return { text, painted: t.paint[look[1]](text) };
+}