linmux 0.1.0

package/dist/lib/install-skill-runtime.js

@@ -0,0 +1,228 @@
+import { LinearAgentError } from "../core/errors/error.js";
+import * as fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+//#region src/lib/install-skill-runtime.ts
+/**
+* `install-skill` runtime — Phase 5 PLAN 05-02 Task 2, DST-06.
+*
+* Pure async function: copies the bundled `skills/linmux/SKILL.md` from
+* the package install path to `~/.claude/skills/linmux/SKILL.md`. No
+* network calls, no workspace resolution.
+*
+* Source resolution: walks two levels up from this file's directory (via
+* `import.meta.url`) and into `skills/linmux/SKILL.md`. Works in BOTH
+* source-checkout layouts (`src/lib/install-skill-runtime.ts` → `../../skills/...`)
+* AND published-tarball layouts (`dist/lib/install-skill-runtime.js` →
+* `../../skills/...`). The `skills/` dir sits at the package root in both.
+*
+* Target resolution: `path.join(os.homedir(), '.claude', 'skills', 'linmux', 'SKILL.md')`
+* — uniform across macOS, Linux, and Windows. Claude Code uses `os.homedir()`
+* everywhere; no `%APPDATA%` branching, no `~` shell expansion.
+*
+* Live-change-detection mitigation (RESEARCH §4 / Pitfall P12): If THIS
+* process created `~/.claude/skills/` (or one of its ancestors) during the
+* mkdir-p step, the envelope includes a `hint` field telling the user to
+* restart Claude Code. We derive that signal from the return value of
+* `mkdirSync({ recursive: true })` — which returns the first directory it
+* actually created — instead of an existsSync check that races with
+* concurrent installs and produces misleading hints.
+*
+* Frontmatter parsing: We parse `metadata.version` from a YAML-ish frontmatter
+* block ourselves rather than depending on `js-yaml`. Rationale: js-yaml is
+* only a transitive dev dep (via @graphql-codegen/cli) and would not be in the
+* published tarball's `node_modules`. Hand-parsing the small subset we need
+* (a string scalar at `metadata.version`) keeps the runtime self-contained
+* and the cold-start budget tight.
+*
+* Error taxonomy (per RESEARCH §11 Option A — both map to EXIT_CODES.GENERIC):
+*   - INSTALL_SKILL_BUNDLE_NOT_FOUND: source missing, frontmatter unparseable,
+*     or `metadata.version` absent. `details.expected_path` always present;
+*     `details.reason` set to 'frontmatter_invalid' or 'version_missing' when
+*     applicable.
+*   - INSTALL_SKILL_WRITE_FAILED: mkdir or writeFile threw an underlying fs
+*     error (EACCES, ENOSPC, etc.). `details.target` and `details.errno`
+*     surface the exact failure.
+*
+* Two-export pattern (S1) is satisfied by this module + `src/commands/install-skill.ts`.
+*/
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_SOURCE = path.resolve(HERE, "..", "..", "skills", "linmux", "SKILL.md");
+const HINT_PARENT_CREATED = "Restart Claude Code if your session predates ~/.claude/skills/.";
+async function installSkillRuntime(input) {
+	const sourcePath = input?.sourcePathOverride ?? DEFAULT_SOURCE;
+	const home = (input?.homedirOverride ?? homedir)();
+	const fsx = input?.fsOverride ?? {
+		readFileSync: fs.readFileSync,
+		writeFileSync: fs.writeFileSync,
+		mkdirSync: fs.mkdirSync,
+		existsSync: fs.existsSync,
+		statSync: fs.statSync
+	};
+	const targetDir = path.join(home, ".claude", "skills", "linmux");
+	const target = path.join(targetDir, "SKILL.md");
+	const parentSkillsDir = path.join(home, ".claude", "skills");
+	let contents;
+	try {
+		contents = fsx.readFileSync(sourcePath, "utf8");
+	} catch (err) {
+		const errno = err?.code ?? "UNKNOWN";
+		throw new LinearAgentError({
+			code: "INSTALL_SKILL_BUNDLE_NOT_FOUND",
+			message: `Could not locate bundled SKILL.md at ${sourcePath}. This usually means linmux was run from a source checkout without a build, or the published tarball is corrupt.`,
+			transient: false,
+			details: {
+				expected_path: sourcePath,
+				resolved_install_path: HERE,
+				errno
+			}
+		});
+	}
+	const version = extractMetadataVersion(contents, sourcePath);
+	const overwritten = fsx.existsSync(target);
+	let parentSkillsCreatedNow = false;
+	try {
+		const created = fsx.mkdirSync(targetDir, { recursive: true });
+		if (typeof created === "string") {
+			const createdResolved = path.resolve(created);
+			const parentResolved = path.resolve(parentSkillsDir);
+			parentSkillsCreatedNow = createdResolved === parentResolved || parentResolved.startsWith(`${createdResolved}${path.sep}`);
+		}
+	} catch (err) {
+		const errno = err?.code ?? "UNKNOWN";
+		throw new LinearAgentError({
+			code: "INSTALL_SKILL_WRITE_FAILED",
+			message: `Could not write SKILL.md to ${target}. Check directory permissions.`,
+			transient: false,
+			details: {
+				target,
+				errno
+			}
+		});
+	}
+	let unchanged = false;
+	if (overwritten) {
+		let existing;
+		try {
+			existing = fsx.readFileSync(target, "utf8");
+		} catch {
+			existing = void 0;
+		}
+		if (existing === contents) unchanged = true;
+	}
+	if (!unchanged) try {
+		fsx.writeFileSync(target, contents, "utf8");
+	} catch (err) {
+		const errno = err?.code ?? "UNKNOWN";
+		throw new LinearAgentError({
+			code: "INSTALL_SKILL_WRITE_FAILED",
+			message: `Could not write SKILL.md to ${target}. Check directory permissions.`,
+			transient: false,
+			details: {
+				target,
+				errno
+			}
+		});
+	}
+	const data = {
+		source: sourcePath,
+		target,
+		bytes_written: unchanged ? 0 : Buffer.byteLength(contents, "utf8"),
+		version,
+		overwritten
+	};
+	if (unchanged) data.unchanged = true;
+	if (parentSkillsCreatedNow) data.hint = HINT_PARENT_CREATED;
+	return {
+		data,
+		meta: {}
+	};
+}
+/**
+* Extract the `metadata.version` field from a SKILL.md's YAML frontmatter.
+*
+* We hand-parse rather than pull in js-yaml because js-yaml is a transitive
+* dev dep only (via @graphql-codegen/cli) and would not be present in the
+* published tarball. Our SKILL.md is authored in-repo, so the frontmatter
+* shape is fully under our control:
+*
+*     ---
+*     name: linmux
+*     description: ...
+*     metadata:
+*       version: "0.1.0"
+*     ---
+*
+* This parser handles:
+*   - quoted (single OR double) and unquoted version strings
+*   - any indentation level under `metadata:` (we look for the first
+*     `version:` line that follows a `metadata:` line)
+*
+* Failure modes (both surface as INSTALL_SKILL_BUNDLE_NOT_FOUND):
+*   - No frontmatter markers at all → reason='frontmatter_invalid'
+*   - Frontmatter present but no `metadata.version` → reason='version_missing'
+*/
+function extractMetadataVersion(contents, sourcePath) {
+	const lines = contents.replace(/^/, "").split(/\r?\n/);
+	if (lines[0]?.trim() !== "---") throw new LinearAgentError({
+		code: "INSTALL_SKILL_BUNDLE_NOT_FOUND",
+		message: `Could not parse YAML frontmatter from ${sourcePath} — missing leading '---' marker.`,
+		transient: false,
+		details: {
+			expected_path: sourcePath,
+			reason: "frontmatter_invalid"
+		}
+	});
+	let endIdx = -1;
+	for (let i = 1; i < lines.length; i++) if (lines[i]?.trim() === "---") {
+		endIdx = i;
+		break;
+	}
+	if (endIdx === -1) throw new LinearAgentError({
+		code: "INSTALL_SKILL_BUNDLE_NOT_FOUND",
+		message: `Could not parse YAML frontmatter from ${sourcePath} — missing closing '---' marker.`,
+		transient: false,
+		details: {
+			expected_path: sourcePath,
+			reason: "frontmatter_invalid"
+		}
+	});
+	const frontmatter = lines.slice(1, endIdx);
+	let inMetadata = false;
+	let metadataIndent = -1;
+	let version;
+	for (const line of frontmatter) {
+		if (/^metadata\s*:\s*$/.test(line)) {
+			inMetadata = true;
+			metadataIndent = line.length - line.trimStart().length;
+			continue;
+		}
+		if (inMetadata) {
+			if (line.trim() === "" || line.trim().startsWith("#")) continue;
+			if (line.length - line.trimStart().length <= metadataIndent) {
+				inMetadata = false;
+				break;
+			}
+			const m = line.match(/^\s*version\s*:\s*(.+?)\s*$/);
+			if (m?.[1]) {
+				let raw = m[1];
+				if (raw.startsWith("\"") && raw.endsWith("\"") || raw.startsWith("'") && raw.endsWith("'")) raw = raw.slice(1, -1);
+				version = raw;
+				break;
+			}
+		}
+	}
+	if (!version) throw new LinearAgentError({
+		code: "INSTALL_SKILL_BUNDLE_NOT_FOUND",
+		message: `Bundled SKILL.md at ${sourcePath} has no metadata.version field in its frontmatter.`,
+		transient: false,
+		details: {
+			expected_path: sourcePath,
+			reason: "version_missing"
+		}
+	});
+	return version;
+}
+//#endregion
+export { installSkillRuntime };

package/dist/lib/introspection-registry.js

@@ -0,0 +1,488 @@
+import { OPERATION_REGISTRY } from "../generated/operations.js";
+import { z } from "zod";
+//#region src/lib/introspection-registry.ts
+/**
+* Introspection registry — Phase 4 PLAN 04-01 spine.
+*
+* Exports:
+*   - `CURATED_REGISTRY` — hand-curated list of all 36 curated commands,
+*     sorted alphabetically by id. Snapshot-pinned in CI (INT-04).
+*   - `CuratedEntry`, `CommandExample`, `RawCommandEntry` — interfaces
+*   - `getRawRegistryView()` — flattened view over OPERATION_REGISTRY for raw introspection
+*
+* InputSchema stubs: all entries use `z.object({})` here. Phase 4 plan 04-03
+* (describe-runtime.ts) replaces stubs with per-command `*InputSchema` exports.
+* The stubs are acceptable because:
+*   1. list-tools only uses `flags[]` names, not the schema object
+*   2. introspection-registry.test.ts verifies structural integrity, not schema contents
+*   3. describe-runtime.ts (04-03) wires real schemas via per-command exports
+*/
+const CURATED_REGISTRY = [
+	{
+		id: "comment create",
+		summary: "Create a new comment on a Linear issue.",
+		flags: [
+			"workspace",
+			"allow-active-workspace-write",
+			"fields",
+			"issue",
+			"body",
+			"parent"
+		],
+		raw_equivalent: "CommentCreate",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "comment delete",
+		summary: "Delete a comment from a Linear issue.",
+		flags: ["workspace", "allow-active-workspace-write"],
+		raw_equivalent: "CommentDelete",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "comment list",
+		summary: "List comments on a Linear issue, with optional related-entity hydration.",
+		flags: [
+			"workspace",
+			"fields",
+			"issue",
+			"include"
+		],
+		raw_equivalent: "Comments",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "comment update",
+		summary: "Update the body of an existing Linear comment.",
+		flags: [
+			"workspace",
+			"allow-active-workspace-write",
+			"fields",
+			"body"
+		],
+		raw_equivalent: "CommentUpdate",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "cycle current",
+		summary: "Retrieve the currently active cycle for a team.",
+		flags: [
+			"workspace",
+			"fields",
+			"team"
+		],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "cycle list",
+		summary: "List all cycles for a team, with optional issue hydration.",
+		flags: [
+			"workspace",
+			"fields",
+			"team",
+			"include"
+		],
+		raw_equivalent: "Cycles",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "cycle move",
+		summary: "Move an issue into a specific cycle number for a team.",
+		flags: [
+			"workspace",
+			"allow-active-workspace-write",
+			"fields",
+			"to"
+		],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "describe",
+		summary: "Return input/output JSON Schema and examples for a curated or raw command.",
+		flags: ["pretty"],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "graphql",
+		summary: "Execute an arbitrary GraphQL query or mutation against Linear.",
+		flags: [
+			"workspace",
+			"allow-active-workspace-write",
+			"allow-mutations",
+			"query",
+			"vars"
+		],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "install-skill",
+		summary: "Copy the bundled Claude Code skill to ~/.claude/skills/linmux/SKILL.md.",
+		flags: ["pretty"],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "issue archive",
+		summary: "Archive a Linear issue (soft-delete; issue remains searchable).",
+		flags: ["workspace", "allow-active-workspace-write"],
+		raw_equivalent: "IssueArchive",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "issue create",
+		summary: "Create a new Linear issue with optional title, description, assignee, team, and more.",
+		flags: [
+			"workspace",
+			"allow-active-workspace-write",
+			"fields",
+			"title",
+			"description",
+			"team",
+			"state",
+			"assignee",
+			"priority",
+			"labels",
+			"project",
+			"cycle",
+			"parent"
+		],
+		raw_equivalent: "IssueCreate",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "issue get",
+		summary: "Fetch a single Linear issue by identifier or UUID.",
+		flags: [
+			"workspace",
+			"fields",
+			"include"
+		],
+		raw_equivalent: "Issue",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "issue list",
+		summary: "List Linear issues with --fields, --limit, --cursor, and Phase 1 filters.",
+		flags: [
+			"workspace",
+			"fields",
+			"limit",
+			"cursor",
+			"state",
+			"assignee",
+			"team",
+			"include"
+		],
+		raw_equivalent: "Issues",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "issue purge",
+		summary: "Permanently delete a Linear issue (irreversible; requires --yes confirmation).",
+		flags: [
+			"workspace",
+			"allow-active-workspace-write",
+			"yes"
+		],
+		raw_equivalent: "IssueDelete",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "issue search",
+		summary: "Full-text search Linear issues with optional filters for state, team, assignee, label, project, and cycle.",
+		flags: [
+			"workspace",
+			"fields",
+			"state",
+			"assignee",
+			"team",
+			"label",
+			"project",
+			"cycle",
+			"no-snippet",
+			"include-archived"
+		],
+		raw_equivalent: "IssueSearch",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "issue transition",
+		summary: "Transition a Linear issue to a new workflow state by name or ID.",
+		flags: [
+			"workspace",
+			"allow-active-workspace-write",
+			"fields"
+		],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "issue trash",
+		summary: "Move a Linear issue to the trash (soft-delete; recoverable from UI).",
+		flags: ["workspace", "allow-active-workspace-write"],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "issue update",
+		summary: "Update fields on an existing Linear issue (title, description, assignee, state, etc.).",
+		flags: [
+			"workspace",
+			"allow-active-workspace-write",
+			"fields",
+			"title",
+			"description",
+			"state",
+			"assignee",
+			"priority",
+			"labels",
+			"project",
+			"cycle"
+		],
+		raw_equivalent: "IssueUpdate",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "label create",
+		summary: "Create a new issue label in a Linear team.",
+		flags: [
+			"workspace",
+			"allow-active-workspace-write",
+			"fields",
+			"name",
+			"team",
+			"color",
+			"description"
+		],
+		raw_equivalent: "IssueLabelCreate",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "label list",
+		summary: "List issue labels for a Linear team or the entire workspace.",
+		flags: [
+			"workspace",
+			"fields",
+			"team"
+		],
+		raw_equivalent: "IssueLabels",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "list-tools",
+		summary: "Enumerate every curated and raw command with curated→raw mappings.",
+		flags: ["pretty"],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "me",
+		summary: "Return the authenticated user and organization details.",
+		flags: ["workspace", "fields"],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "project create",
+		summary: "Create a new Linear project with optional name, description, teams, state, and dates.",
+		flags: [
+			"workspace",
+			"allow-active-workspace-write",
+			"fields",
+			"name",
+			"teams",
+			"description",
+			"state",
+			"lead",
+			"start-date",
+			"target-date"
+		],
+		raw_equivalent: "ProjectCreate",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "project get",
+		summary: "Fetch a single Linear project by ID or name.",
+		flags: [
+			"workspace",
+			"fields",
+			"include"
+		],
+		raw_equivalent: "Project",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "project list",
+		summary: "List all Linear projects in the workspace.",
+		flags: ["workspace", "fields"],
+		raw_equivalent: "Projects",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "project update",
+		summary: "Update fields on an existing Linear project (name, description, state).",
+		flags: [
+			"workspace",
+			"allow-active-workspace-write",
+			"fields",
+			"name",
+			"description",
+			"state"
+		],
+		raw_equivalent: "ProjectUpdate",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "project update-status",
+		summary: "Set a Linear project's current status (e.g. 'On Track' -> 'At Risk').",
+		flags: [
+			"workspace",
+			"allow-active-workspace-write",
+			"fields"
+		],
+		raw_equivalent: "ProjectUpdate",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "raw",
+		summary: "Execute any operation from the full Linear GraphQL registry by PascalCase name.",
+		flags: [
+			"workspace",
+			"allow-active-workspace-write",
+			"allow-mutations",
+			"vars"
+		],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "raw batch",
+		summary: "Execute a batch of raw Linear GraphQL operations from a plan file.",
+		flags: [
+			"workspace",
+			"allow-active-workspace-write",
+			"allow-mutations",
+			"plan",
+			"dry-run",
+			"yes"
+		],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "schema",
+		summary: "Return the Linear GraphQL schema as compact SDL or introspection JSON.",
+		flags: [
+			"pretty",
+			"full",
+			"json"
+		],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "state list",
+		summary: "List workflow states for a Linear team.",
+		flags: [
+			"workspace",
+			"fields",
+			"team"
+		],
+		raw_equivalent: "WorkflowStates",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "team get",
+		summary: "Fetch details for a single Linear team by key, name, or ID.",
+		flags: ["workspace", "fields"],
+		raw_equivalent: "Team",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "team list",
+		summary: "List all Linear teams in the workspace.",
+		flags: ["workspace", "fields"],
+		raw_equivalent: "Teams",
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "whoami",
+		summary: "Alias for `me` — return the authenticated user and organization details.",
+		flags: ["workspace", "fields"],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "workspace add",
+		summary: "Add a new Linear workspace to the local config with a personal API token.",
+		flags: ["token"],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "workspace list",
+		summary: "List all configured Linear workspaces in the local config.",
+		flags: [],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "workspace remove",
+		summary: "Remove a Linear workspace from the local config.",
+		flags: [],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "workspace replace-token",
+		summary: "Replace the API token for an existing workspace in the local config.",
+		flags: ["token"],
+		inputSchema: z.object({}),
+		examples: []
+	},
+	{
+		id: "workspace use",
+		summary: "Set the active default workspace used when no --workspace flag is provided.",
+		flags: [],
+		inputSchema: z.object({}),
+		examples: []
+	}
+];
+/**
+* Convenience view over OPERATION_REGISTRY for introspection commands.
+* Returns all operations with their name and kind (query | mutation).
+*/
+function getRawRegistryView() {
+	return Object.entries(OPERATION_REGISTRY).map(([name, entry]) => ({
+		name,
+		kind: entry.kind
+	}));
+}
+//#endregion
+export { CURATED_REGISTRY, getRawRegistryView };