linmux 0.1.0

package/dist/core/output/envelope.js

@@ -0,0 +1,53 @@
+//#region src/core/output/envelope.ts
+/**
+* Build a stable Meta record with the canonical key order:
+*   command, workspace, workspaceSource, pageInfo, complexity, totalCount, batch
+* Optional fields with `undefined` values are omitted; `null` workspaces
+* are preserved (they are meaningful — "ran via LINEAR_API_KEY env").
+*
+* `complexity` and `totalCount` are Phase 2 additions (PLAN 02-01). `batch`
+* is a Phase 3 PLAN 03-01 addition. They are appended in the order they
+* were added so any envelope that omits them serializes identically to its
+* Phase 1/2 byte-for-byte form.
+*/
+function buildMeta(meta) {
+	const out = { command: meta.command };
+	if (meta.workspace !== void 0) out.workspace = meta.workspace;
+	if (meta.workspaceSource !== void 0) out.workspaceSource = meta.workspaceSource;
+	if (meta.pageInfo !== void 0) out.pageInfo = meta.pageInfo;
+	if (meta.complexity !== void 0) out.complexity = meta.complexity;
+	if (meta.totalCount !== void 0) out.totalCount = meta.totalCount;
+	if (meta.batch !== void 0) out.batch = meta.batch;
+	return out;
+}
+function buildFailureMeta(meta) {
+	const out = { command: meta.command };
+	if (meta.workspace !== void 0) out.workspace = meta.workspace;
+	if (meta.workspaceSource !== void 0) out.workspaceSource = meta.workspaceSource;
+	return out;
+}
+function success(data, meta) {
+	return {
+		$apiVersion: "1",
+		ok: true,
+		data,
+		meta: buildMeta(meta)
+	};
+}
+function failure(error, meta) {
+	const errOut = {
+		code: error.code,
+		message: error.message,
+		transient: error.transient
+	};
+	if (error.retryAfterMs !== void 0) errOut.retryAfterMs = error.retryAfterMs;
+	if (error.details !== void 0) errOut.details = error.details;
+	return {
+		$apiVersion: "1",
+		ok: false,
+		error: errOut,
+		meta: buildFailureMeta(meta)
+	};
+}
+//#endregion
+export { failure, success };

package/dist/core/output/format.js

@@ -0,0 +1,42 @@
+import { redact } from "../redact/redact.js";
+import pc from "picocolors";
+//#region src/core/output/format.ts
+function format(envelope, opts) {
+	const redacted = redact(envelope);
+	if (!opts.pretty) return { stdout: `${JSON.stringify(redacted)}\n` };
+	if (redacted.ok) {
+		if (!("meta" in redacted)) return { stdout: `${JSON.stringify(redacted)}\n` };
+		return { stdout: renderSuccessPretty(redacted) };
+	}
+	return {
+		stdout: renderFailurePretty(redacted),
+		stderr: renderFailureStderrSummary(redacted)
+	};
+}
+function renderSuccessPretty(env) {
+	const lines = [];
+	const header = `${env.meta.command}${env.meta.workspace ? ` · ${env.meta.workspace}` : ""}`;
+	lines.push(pc.dim(`# ${header}`));
+	lines.push(JSON.stringify(env.data, null, 2));
+	if (env.meta.pageInfo) {
+		const pi = env.meta.pageInfo;
+		lines.push(pc.dim(`# pageInfo: hasNextPage=${pi.hasNextPage}${pi.endCursor ? ` endCursor=${pi.endCursor}` : ""}`));
+	}
+	return `${lines.join("\n")}\n`;
+}
+function renderFailurePretty(env) {
+	const lines = [];
+	lines.push(`${pc.bold(pc.red("error:"))} ${env.error.code} — ${env.error.message}`);
+	if (env.error.transient) {
+		const retry = env.error.retryAfterMs !== void 0 ? ` (retry after ${env.error.retryAfterMs}ms)` : "";
+		lines.push(pc.dim(`# transient${retry} — safe to retry`));
+	}
+	if (env.error.details) for (const [k, v] of Object.entries(env.error.details)) lines.push(`  ${pc.dim(k)}: ${typeof v === "string" ? v : JSON.stringify(v)}`);
+	lines.push(pc.dim("# see stderr for one-liner; full envelope on stdout above"));
+	return `${lines.join("\n")}\n`;
+}
+function renderFailureStderrSummary(env) {
+	return `${pc.bold(pc.red("error:"))} ${env.error.code} — ${env.error.message}\n`;
+}
+//#endregion
+export { format };

package/dist/core/output/index.js

@@ -0,0 +1,3 @@
+import "./envelope.js";
+import "./format.js";
+export {};

package/dist/core/pagination/flags.js

@@ -0,0 +1,29 @@
+import { LinearAgentError } from "../errors/error.js";
+import { Flags } from "@oclif/core";
+const PAGINATION_FLAGS = {
+	limit: Flags.integer({
+		description: `Page size (default 25, max 100)`,
+		default: 25,
+		min: 1,
+		max: 100
+	}),
+	cursor: Flags.string({ description: "Opaque cursor from a previous response's meta.pageInfo.endCursor" })
+};
+function parsePagination(input) {
+	const limit = input.limit ?? 25;
+	if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw new LinearAgentError({
+		code: "USAGE_ERROR",
+		message: `--limit must be an integer between 1 and 100`,
+		details: {
+			received: limit,
+			min: 1,
+			max: 100
+		}
+	});
+	return {
+		first: limit,
+		after: input.cursor
+	};
+}
+//#endregion
+export { PAGINATION_FLAGS, parsePagination };

package/dist/core/pagination/index.js

@@ -0,0 +1,2 @@
+import "./flags.js";
+export {};

package/dist/core/projection/presets.js

@@ -0,0 +1,116 @@
+const FIELD_PRESETS = {
+	issue: {
+		ids: ["id", "identifier"],
+		defaults: [
+			"id",
+			"identifier",
+			"title",
+			"state.name",
+			"priority",
+			"assignee.email",
+			"team.key",
+			"updatedAt"
+		],
+		full: "*"
+	},
+	comment: {
+		ids: ["id"],
+		defaults: [
+			"id",
+			"body",
+			"user.email",
+			"user.name",
+			"issue.identifier",
+			"parent.id",
+			"createdAt",
+			"updatedAt"
+		],
+		full: "*"
+	},
+	project: {
+		ids: ["id"],
+		defaults: [
+			"id",
+			"name",
+			"state",
+			"progress",
+			"targetDate",
+			"lead.email",
+			"description",
+			"updatedAt"
+		],
+		full: "*"
+	},
+	cycle: {
+		ids: ["id"],
+		defaults: [
+			"id",
+			"number",
+			"name",
+			"startsAt",
+			"endsAt",
+			"progress",
+			"team.key",
+			"isActive"
+		],
+		full: "*"
+	},
+	team: {
+		ids: ["id", "key"],
+		defaults: [
+			"id",
+			"key",
+			"name",
+			"description",
+			"color",
+			"private",
+			"createdAt",
+			"cycleEnabled"
+		],
+		full: "*"
+	},
+	label: {
+		ids: ["id"],
+		defaults: [
+			"id",
+			"name",
+			"color",
+			"description",
+			"team.key",
+			"parent.name",
+			"createdAt",
+			"updatedAt"
+		],
+		full: "*"
+	},
+	state: {
+		ids: ["id"],
+		defaults: [
+			"id",
+			"name",
+			"type",
+			"color",
+			"position",
+			"team.key",
+			"description",
+			"createdAt"
+		],
+		full: "*"
+	},
+	user: {
+		ids: ["id"],
+		defaults: [
+			"id",
+			"name",
+			"email",
+			"displayName",
+			"admin",
+			"isMe",
+			"active",
+			"avatarUrl"
+		],
+		full: "*"
+	}
+};
+//#endregion
+export { FIELD_PRESETS };

package/dist/core/projection/project.js

@@ -0,0 +1,282 @@
+import { LinearAgentError } from "../errors/error.js";
+import { FIELD_PRESETS } from "./presets.js";
+//#region src/core/projection/project.ts
+/**
+* Field projection — parses the `--fields` flag and projects an arbitrary
+* value tree to the requested dot-paths.
+*
+* Two-stage pipeline (KRN-08, ISS-01):
+*   1. parseFields(input, entity) → `ProjectionSpec` (preset paths or sentinel)
+*      - Preset names ("ids" / "defaults" / "full") resolve to the entity's
+*        preset entry.
+*      - Custom CSV ("id,title,state.name") is split, trimmed, and validated
+*        against the entity's allowed-field registry. Unknown paths throw
+*        `INVALID_FIELD` (exit 2).
+*   2. project(value, spec) → projected value
+*      - For `FULL_PRESET`, returns the input unchanged (deep-clone not
+*        required; identity is preserved).
+*      - For a path array, walks each dot-path and copies the leaf into a
+*        fresh object tree. Missing nested keys yield `null` rather than
+*        throwing — agents reading the envelope can rely on "key present"
+*        being a stable contract independent of upstream data shape.
+*
+* Allowed-field registry: a per-entity `Set<string>` of dot-paths. Phase 1
+* only registers the `issue` entity; Phase 2 extends this to every curated
+* read command. The registry is the contract for what `--fields` accepts —
+* widening it requires a deliberate code change + a test.
+*
+* Threat model (T-01-25, T-01-26):
+*   - Custom field paths are untrusted input; the registry gates them.
+*   - Filter values surfaced in `INVALID_FIELD` details are the user's own
+*     CSV input (not secrets) — kernel redactor still scrubs token-shaped
+*     substrings as defense in depth.
+*/
+/**
+* Allowed dot-paths per entity. Custom `--fields` CSV values are validated
+* against this registry; unknown paths trigger `INVALID_FIELD`.
+*
+* The list is intentionally generous (we'd rather accept a field and get
+* `null` from `project()` than reject a perfectly valid SDK field). Phase 2
+* expands this as new commands ship; Phase 3's raw GraphQL passthrough side-
+* steps the registry entirely.
+*/
+const ALLOWED_FIELDS = {
+	issue: new Set([
+		"id",
+		"identifier",
+		"title",
+		"description",
+		"priority",
+		"priorityLabel",
+		"estimate",
+		"sortOrder",
+		"createdAt",
+		"updatedAt",
+		"archivedAt",
+		"completedAt",
+		"startedAt",
+		"canceledAt",
+		"dueDate",
+		"snoozedUntilAt",
+		"snippet",
+		"state.id",
+		"state.name",
+		"state.type",
+		"assignee.id",
+		"assignee.email",
+		"assignee.name",
+		"team.id",
+		"team.key",
+		"team.name",
+		"project.id",
+		"project.name",
+		"cycle.id",
+		"cycle.number",
+		"parent.id",
+		"parent.identifier",
+		"url"
+	]),
+	comment: new Set([
+		"id",
+		"body",
+		"bodyData",
+		"editedAt",
+		"createdAt",
+		"updatedAt",
+		"archivedAt",
+		"url",
+		"user.id",
+		"user.email",
+		"user.name",
+		"user.displayName",
+		"issue.id",
+		"issue.identifier",
+		"issue.title",
+		"parent.id",
+		"reactions"
+	]),
+	project: new Set([
+		"id",
+		"name",
+		"description",
+		"state",
+		"progress",
+		"sortOrder",
+		"startDate",
+		"targetDate",
+		"startedAt",
+		"completedAt",
+		"canceledAt",
+		"archivedAt",
+		"createdAt",
+		"updatedAt",
+		"color",
+		"icon",
+		"slugId",
+		"url",
+		"lead.id",
+		"lead.email",
+		"lead.name",
+		"creator.id",
+		"creator.email",
+		"creator.name"
+	]),
+	cycle: new Set([
+		"id",
+		"number",
+		"name",
+		"description",
+		"startsAt",
+		"endsAt",
+		"completedAt",
+		"progress",
+		"isActive",
+		"isPast",
+		"isFuture",
+		"isNext",
+		"isPrevious",
+		"createdAt",
+		"updatedAt",
+		"archivedAt",
+		"team.id",
+		"team.key",
+		"team.name"
+	]),
+	team: new Set([
+		"id",
+		"key",
+		"name",
+		"description",
+		"color",
+		"icon",
+		"private",
+		"cycleEnabled",
+		"cycleDuration",
+		"cycleStartDay",
+		"cycleCooldownTime",
+		"cycleIssueAutoAssignStarted",
+		"cycleIssueAutoAssignCompleted",
+		"cycleLockToActive",
+		"createdAt",
+		"updatedAt",
+		"archivedAt",
+		"inviteHash",
+		"timezone",
+		"autoArchivePeriod",
+		"autoClosePeriod",
+		"defaultIssueEstimate",
+		"issueOrderingNoPriorityFirst",
+		"issueSortOrderDefaultToBottom"
+	]),
+	label: new Set([
+		"id",
+		"name",
+		"color",
+		"description",
+		"createdAt",
+		"updatedAt",
+		"archivedAt",
+		"team.id",
+		"team.key",
+		"team.name",
+		"parent.id",
+		"parent.name",
+		"creator.id",
+		"creator.email",
+		"creator.name"
+	]),
+	state: new Set([
+		"id",
+		"name",
+		"type",
+		"color",
+		"position",
+		"description",
+		"createdAt",
+		"updatedAt",
+		"archivedAt",
+		"team.id",
+		"team.key",
+		"team.name"
+	]),
+	user: new Set([
+		"id",
+		"name",
+		"email",
+		"displayName",
+		"admin",
+		"isMe",
+		"active",
+		"guest",
+		"avatarUrl",
+		"avatarBackgroundColor",
+		"description",
+		"statusEmoji",
+		"statusLabel",
+		"statusUntilAt",
+		"timezone",
+		"createdAt",
+		"updatedAt",
+		"archivedAt",
+		"lastSeen",
+		"inviteHash",
+		"url"
+	])
+};
+function parseFields(input, entity) {
+	const normalized = input.trim();
+	const presets = FIELD_PRESETS[entity];
+	if (normalized === "ids") return presets.ids;
+	if (normalized === "defaults") return presets.defaults;
+	if (normalized === "full") return "*";
+	const paths = normalized.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
+	const allowed = ALLOWED_FIELDS[entity];
+	const unknown = paths.filter((p) => !allowed.has(p));
+	if (unknown.length > 0) throw new LinearAgentError({
+		code: "INVALID_FIELD",
+		message: `unknown field(s) for ${entity}: ${unknown.join(", ")}`,
+		details: {
+			entity,
+			unknown,
+			allowed: [...allowed].sort()
+		}
+	});
+	return paths;
+}
+/**
+* Walk `value` and pull out only the requested dot-paths. For each leaf:
+*   - If the upstream key exists, copy the value (no clone — references
+*     into the SDK shape are fine because we never mutate the result).
+*   - If the upstream key is missing at any level, the leaf is `null`.
+*
+* For `FULL_PRESET`, returns the input unchanged.
+*/
+function project(value, spec) {
+	if (spec === "*") return value;
+	if (spec.length === 0) return {};
+	const out = {};
+	for (const path of spec) {
+		const parts = path.split(".");
+		let src = value;
+		let dst = out;
+		for (let i = 0; i < parts.length; i++) {
+			const key = parts[i];
+			const isLeaf = i === parts.length - 1;
+			const srcValue = readKey(src, key);
+			if (isLeaf) dst[key] = srcValue ?? null;
+			else {
+				if (!(key in dst) || typeof dst[key] !== "object" || dst[key] === null) dst[key] = {};
+				dst = dst[key];
+				src = srcValue;
+			}
+		}
+	}
+	return out;
+}
+function readKey(value, key) {
+	if (value === null || typeof value !== "object") return void 0;
+	if (!(key in value)) return void 0;
+	return value[key];
+}
+//#endregion
+export { parseFields, project };

package/dist/core/redact/redact.js

@@ -0,0 +1,45 @@
+//#region src/core/redact/redact.ts
+/**
+* Token redactor — last-line-of-defense scrubber for Linear PATs.
+*
+* The kernel's `format()` function in `src/core/output/format.ts` calls
+* `redact()` on every envelope before stringifying it. Property-based
+* tests in `test/core/redact.test.ts` (≥200 runs) prove no
+* `lin_api_*` or `lin_oauth_*` substring can survive a round-trip.
+*
+* Why the regex is permissive on length: Linear PATs are currently 40-ish
+* base64url chars after the prefix, but the public format isn't versioned.
+* `[A-Za-z0-9_-]+` matches greedily on token-shaped suffixes — slightly
+* over-aggressive on otherwise-innocuous strings is the right tradeoff for
+* a security boundary (PITFALLS § Pitfalls 3, 4).
+*/
+const REDACTED = "[REDACTED]";
+const TOKEN_PATTERN = /lin_(?:api|oauth)_[A-Za-z0-9_-]+/g;
+const CIRCULAR_SENTINEL = "[CIRCULAR]";
+/**
+* Walk an arbitrary value and replace every Linear-PAT-shaped substring
+* inside any string field with `[REDACTED]`. Returns a new value (does
+* not mutate the input). Cycle-safe: revisited objects/arrays return the
+* `[CIRCULAR]` sentinel so the walk is bounded (T-01-04 in the threat
+* model).
+*
+* Type parameter `T` is preserved as a return-type hint, but the runtime
+* value MAY differ from `T` if the input contains cycles (the `[CIRCULAR]`
+* sentinel is a string, not the original object). Callers feeding cyclic
+* inputs should not rely on the static return type past one level.
+*/
+function redact(input) {
+	return walk(input, /* @__PURE__ */ new WeakSet());
+}
+function walk(value, seen) {
+	if (typeof value === "string") return value.replace(TOKEN_PATTERN, REDACTED);
+	if (value === null || typeof value !== "object") return value;
+	if (seen.has(value)) return CIRCULAR_SENTINEL;
+	seen.add(value);
+	if (Array.isArray(value)) return value.map((v) => walk(v, seen));
+	const out = {};
+	for (const [k, v] of Object.entries(value)) out[k] = walk(v, seen);
+	return out;
+}
+//#endregion
+export { redact };

package/dist/core/resolvers/cycle.js

@@ -0,0 +1,60 @@
+import { LinearAgentError } from "../errors/error.js";
+import { withRateLimitRetry } from "../transport/rate-limit.js";
+import { UUID_RE } from "../../lib/filter-heuristics.js";
+//#region src/core/resolvers/cycle.ts
+const cache = /* @__PURE__ */ new Map();
+/** Matches `+N`, `-N`, and bare `N` integer offsets like `0`, `+1`, `-3`. */
+const OFFSET_RE = /^[+-]?\d+$/;
+/**
+* Resolve a cycle reference (UUID, `current`, `next`, `previous`, `+N`, `-N`,
+* `0`, or cycle name) to a cycle UUID, scoped to one `${workspace}:${teamId}`
+* pair.
+*/
+async function resolveCycleId(client, workspaceName, teamId, ref, retryOpts) {
+	if (UUID_RE.test(ref)) return ref;
+	const key = `${workspaceName}:${teamId}`;
+	let cyclesP = cache.get(key);
+	if (!cyclesP) {
+		cyclesP = (async () => {
+			const team = await withRateLimitRetry(() => client.team(teamId), retryOpts);
+			return (await withRateLimitRetry(() => team.cycles({ first: 250 }), retryOpts)).nodes.map((c) => ({
+				id: c.id,
+				number: c.number,
+				name: c.name ?? null,
+				isActive: c.isActive ?? false
+			})).sort((a, b) => a.number - b.number);
+		})();
+		cache.set(key, cyclesP);
+	}
+	let cycles;
+	try {
+		cycles = await cyclesP;
+	} catch (e) {
+		cache.delete(key);
+		throw e;
+	}
+	const activeIdx = cycles.findIndex((c) => c.isActive);
+	const findOffset = (delta) => {
+		if (activeIdx === -1) return void 0;
+		return cycles[activeIdx + delta];
+	};
+	let resolved;
+	if (ref === "current") resolved = activeIdx >= 0 ? cycles[activeIdx] : void 0;
+	else if (ref === "next") resolved = findOffset(1);
+	else if (ref === "previous") resolved = findOffset(-1);
+	else if (OFFSET_RE.test(ref)) resolved = findOffset(Number.parseInt(ref, 10));
+	else resolved = cycles.find((c) => c.name?.toLowerCase() === ref.toLowerCase());
+	if (!resolved) throw new LinearAgentError({
+		code: "CYCLE_NOT_FOUND",
+		message: `cycle not found: ${ref}`,
+		details: {
+			teamId,
+			requested: ref,
+			availableNumbers: cycles.map((c) => c.number),
+			activeNumber: activeIdx >= 0 ? cycles[activeIdx]?.number ?? null : null
+		}
+	});
+	return resolved.id;
+}
+//#endregion
+export { resolveCycleId };

package/dist/core/resolvers/index.js

@@ -0,0 +1,7 @@
+import "./cycle.js";
+import "./label.js";
+import "./project.js";
+import "./project-status.js";
+import "./state.js";
+import "./team.js";
+export {};

package/dist/core/resolvers/label.js

@@ -0,0 +1,54 @@
+import { LinearAgentError } from "../errors/error.js";
+import { withRateLimitRetry } from "../transport/rate-limit.js";
+import { UUID_RE } from "../../lib/filter-heuristics.js";
+//#region src/core/resolvers/label.ts
+const cache = /* @__PURE__ */ new Map();
+/**
+* Resolve a label name (or UUID) to a label UUID, scoped to one
+* `${workspace}:${teamId}` pair.
+*/
+async function resolveLabelId(client, workspaceName, teamId, nameOrId, retryOpts) {
+	if (UUID_RE.test(nameOrId)) return nameOrId;
+	const key = `${workspaceName}:${teamId}`;
+	let map = cache.get(key);
+	if (!map) {
+		map = (async () => {
+			const conn = await withRateLimitRetry(() => client.issueLabels({
+				filter: { team: { id: { eq: teamId } } },
+				first: 250
+			}), retryOpts);
+			const m = /* @__PURE__ */ new Map();
+			for (const l of conn.nodes) m.set(l.name.toLowerCase(), l.id);
+			return m;
+		})();
+		cache.set(key, map);
+	}
+	let m;
+	try {
+		m = await map;
+	} catch (e) {
+		cache.delete(key);
+		throw e;
+	}
+	const id = m.get(nameOrId.toLowerCase());
+	if (!id) throw new LinearAgentError({
+		code: "LABEL_NOT_FOUND",
+		message: `label not found: ${nameOrId}`,
+		details: {
+			teamId,
+			requested: nameOrId,
+			available: [...m.keys()].sort()
+		}
+	});
+	return id;
+}
+/**
+* Resolve a list of label names/UUIDs to label UUIDs in input order. Shares
+* the underlying per-team cache so a list of N names triggers at most one SDK
+* call (subsequent name lookups read from the cached map; UUIDs pass through).
+*/
+async function resolveLabelIds(client, workspaceName, teamId, namesOrIds, retryOpts) {
+	return Promise.all(namesOrIds.map((n) => resolveLabelId(client, workspaceName, teamId, n, retryOpts)));
+}
+//#endregion
+export { resolveLabelId, resolveLabelIds };