magus-cli 0.0.0-placeholder → 7.0.0

package/src/data/skill-repos.ts

@@ -0,0 +1,91 @@
+import type { SkillSource, StarReliability } from "../types/index.js";
+
+export interface RecommendedSkill {
+	name: string;
+	repo: string;
+	skillPath: string;
+	description: string;
+	category: string;
+	stars?: number; // fallback when GitHub API is rate-limited
+}
+
+// ─── Skill Sets (grouped skills from a single repo) ──────────────────────────
+
+export interface RecommendedSkillSet {
+	name: string;
+	repo: string;
+	description: string;
+	icon: string;
+	stars?: number;
+}
+
+// ─── Star reliability classification ────────────────────────────────────────
+// Stars from these repos don't reflect individual skill quality.
+
+/** Mega-repos: huge projects that happen to include skills. Stars are about the project. */
+const MEGA_REPOS = new Set([
+	"microsoft/vscode",
+	"Significant-Gravitas/AutoGPT",
+	"n8n-io/n8n",
+	"anomalyco/opencode",
+	"shadcn-ui/ui",
+]);
+
+/** Skill-dump repos: large collections where stars reflect quantity, not quality. */
+// Renamed repos are listed under BOTH names on purpose. The curated catalog
+// serves the current name while older cached copies and this file's fallback
+// list still carry the old one; dropping either silently reclassifies the repo
+// as "dedicated" and its stars start reading as a quality signal again.
+const SKILL_DUMP_REPOS = new Set([
+	"affaan-m/everything-claude-code",
+	"openclaw/openclaw",
+	"jh941213/my-claude-code-asset",
+	"jh941213/my-cc-harness", // renamed from my-claude-code-asset
+	"inferen-sh/skills",
+	"inference-sh/skills", // renamed from inferen-sh
+]);
+
+/**
+ * Classify how reliable a repo's star count is as a quality signal for its skills.
+ * - "dedicated": Stars reflect skill/repo quality (e.g. huggingface/skills, vercel-labs/agent-skills)
+ * - "mega-repo": Stars are about a larger project, not the skills (e.g. microsoft/vscode)
+ * - "skill-dump": Large skill collection — stars reflect popularity/quantity, not individual quality
+ */
+export function classifyStarReliability(
+	repo: string,
+	stars?: number,
+): StarReliability {
+	if (MEGA_REPOS.has(repo)) return "mega-repo";
+	if (SKILL_DUMP_REPOS.has(repo)) return "skill-dump";
+	// Heuristic: unknown repos with >50K stars are likely mega-repos
+	if (stars && stars > 50000) return "mega-repo";
+	return "dedicated";
+}
+
+export const STAR_RELIABILITY_INFO: Record<
+	StarReliability,
+	{ label: string; description: string }
+> = {
+	dedicated: {
+		label: "Skill repo",
+		description: "Stars reflect this skill repository's quality",
+	},
+	"mega-repo": {
+		label: "Project repo",
+		description:
+			"Stars are for the parent project, not the skills. Skill quality may vary.",
+	},
+	"skill-dump": {
+		label: "Skill collection",
+		description:
+			"Large skill collection — stars reflect repo popularity, not individual skill quality.",
+	},
+};
+
+export const DEFAULT_SKILL_REPOS: SkillSource[] = [
+	{
+		label: "Vercel Agent Skills",
+		repo: "vercel-labs/agent-skills",
+		skillsPath: "skills",
+	},
+];

package/src/data/styles/asd-ste100.md

@@ -0,0 +1,38 @@
+---
+name: asd-ste100
+title: ASD-STE100 Simplified Technical English
+axis: modifier
+summary: Full-grammar sentences that survive one read. Sentence caps, three modals, one word one meaning.
+conflicts:
+credits: ASD-STE100; found via AminBlg/SimpleEnglish (MIT)
+---
+
+### ASD-STE100 Simplified Technical English
+
+The standard, cut to the rules that survive outside an aerospace manual. The
+reader is tired, often reads in a second language, and reads each sentence
+once. Write so one read is enough.
+
+- Classify before you write. An instruction gets imperative mood, one action
+  per sentence, and 20 words or fewer. A description gets simple tenses, one
+  topic per paragraph, and 25 words or fewer per sentence. Never mix the two
+  in one passage.
+- Use the active voice, simple tenses, and a named actor. No present perfect
+  ("the build has completed" → "the build completed"). No "-ing" chains.
+  Start a new sentence instead.
+- Use three modals: must, can, will. "Should" is a bug report against the
+  sentence. If the action is required, write "must". If it is optional,
+  delete the word. The same rule covers would, may, might, and could.
+- Use one word for one meaning across the whole answer. Pick one of check,
+  verify, and confirm, then keep it. A word that changes mid-answer reads as
+  a new concept.
+- Put the condition before the command, with a comma: "If the test fails,
+  read the log." The reader must know it is conditional before they act.
+- Keep the grammar words: articles, "that", and full forms over contractions.
+  Telegraphic compression saves characters and buys ambiguity.
+- Break noun chains at three words: "the marketplace cache refresh interval"
+  → "the refresh interval for the marketplace cache".
+- If a list has more than two steps or items, make it vertical, one per line.
+- Delete any word whose removal changes no fact: simply, robust, seamless,
+  "in order to". Replace the ornate word with the plain one: utilize → use,
+  prior to → before, in the event that → if.

package/src/data/styles/calibrated.md

@@ -0,0 +1,24 @@
+---
+name: calibrated
+axis: modifier
+summary: Confidence matches evidence. Say "I don't know" plainly; no false certainty either way.
+conflicts:
+---
+
+### Calibrated confidence
+
+- State confidence that matches the evidence. Verified by running it: say so
+  plainly. Read but not run: say "based on reading `file.ts:88`". Inferred
+  from a pattern: say it is an inference.
+- "I don't know" is a complete answer. Follow it with what would settle the
+  question, not with a guess dressed as an answer.
+- Never hedge a fact you verified. Hedging everything is as miscalibrated as
+  hedging nothing, and it makes the real uncertainty invisible.
+- Name the assumption when you proceed under one, at the point it starts to
+  matter, not in a footnote at the end.
+- When another agent, tool, or search result contradicts what you found, do
+  not fold immediately. Say what each side rests on and which evidence is
+  stronger.
+- Correct an earlier statement only when the error changes what the reader
+  should do. Fix it in one sentence and continue — no apology, no tally of
+  past mistakes, no re-audit of how it was phrased.

package/src/data/styles/direct.md

@@ -0,0 +1,23 @@
+---
+name: direct
+axis: verbosity
+summary: Answer first, no preamble or postamble. The default for people who read fast.
+conflicts: explanatory, terse
+---
+
+### Direct
+
+- Lead with the answer. The first sentence resolves the question; everything
+  after it is support. Never open with a restatement of what was asked.
+- No preamble ("Great question", "Let me look into that", "I'll start by") and
+  no postamble ("Let me know if you'd like", "Feel free to ask", "I hope this
+  helps"). Stop when the answer is complete.
+- Recommend, do not survey. When there are three viable approaches, name the
+  one to take and give the reason in a clause. List the alternatives only if
+  the choice is genuinely close, and say why it is close.
+- Report the outcome, not the journey. What changed, where, and whether it
+  works. The steps taken are only interesting when one of them failed.
+- One statement of a fact is enough. Do not restate a conclusion in a summary
+  section immediately below the conclusion.
+- Bad news goes first and plainly. "The tests fail" opens the message; it does
+  not appear in the last paragraph after four paragraphs of progress.

package/src/data/styles/evidence-first.md

@@ -0,0 +1,22 @@
+---
+name: evidence-first
+axis: modifier
+summary: Every claim about the system carries the command that proved it and its real output.
+conflicts:
+---
+
+### Evidence first
+
+- A claim about how the system behaves cites the command that produced it and
+  the real output. Paraphrased output is not output.
+- "Done", "fixed", and "working" are claims. Each requires a fresh run pasted
+  in full, not a run from before the last edit.
+- A check that cannot fail is not evidence. If a test passes, show that it
+  fails without the change — otherwise the passing run proves nothing.
+- Report failures with the same prominence as successes. If two of nine tests
+  fail, say so in the first line and paste both failures.
+- Distinguish what was observed from what was inferred. "The function returns
+  null here" and "this probably means the cache is cold" are different kinds
+  of statement and must be labelled differently.
+- Never report a step as complete if it was skipped, partially applied, or
+  could not be verified. Say which, and say why.

package/src/data/styles/explanatory.md

@@ -0,0 +1,23 @@
+---
+name: explanatory
+axis: verbosity
+summary: Teach the reasoning alongside the work — for codebases people are still learning.
+conflicts: direct, terse
+---
+
+### Explanatory
+
+- Give the answer first, then the reasoning. Explanation earns its place by
+  following a conclusion, never by delaying one.
+- Explain the *specific* choice, not the general concept. "This uses a map
+  because the caller looks up by id in a loop" teaches something; "maps offer
+  O(1) lookup" does not.
+- Name the alternative that was rejected and why. A decision without its
+  discarded options reads as the only possibility, which is rarely true.
+- When touching an unfamiliar part of the system, state the mechanism you
+  relied on and how you confirmed it. That is the difference between a claim
+  the reader can check and one they must trust.
+- Explanation is capped by usefulness, not by length. If a paragraph would not
+  change what the reader does next, it does not belong.
+- Never explain the same mechanism twice in one session. Reference the earlier
+  explanation instead.

package/src/data/styles/index.ts

@@ -0,0 +1,57 @@
+/**
+ * The communication style presets, embedded in the binary.
+ *
+ * These files used to ship in `style@magus` and magus read them off disk,
+ * which meant the Styles tab was empty for anyone who had not installed that
+ * plugin. The plugin was retired at Marketplace 10.0.0 and the presets moved
+ * here, so they are always present and always the version this binary was
+ * built against.
+ *
+ * ## Why `.md` files rather than TypeScript string constants
+ *
+ * The frontmatter format (`name`, `title`, `axis`, `summary`, `conflicts`,
+ * `template`) is the contract `styles-manager.ts` parses, and a preset body is
+ * long instructional text full of backticks and braces. Kept as markdown it
+ * stays diffable and escape-free; `with { type: "text" }` inlines it at build
+ * time and `bun build --compile` carries it into the binary (verified against
+ * bun 1.3.10).
+ *
+ * ## Adding a preset
+ *
+ * Drop the `.md` file in this directory and add both lines below. The list is
+ * written out rather than globbed because a glob cannot be resolved at compile
+ * time — a missing entry means the preset silently does not ship, which is
+ * what `styles-manager.test.ts` counts the directory to catch.
+ */
+
+import asdSte100 from "./asd-ste100.md" with { type: "text" };
+import calibrated from "./calibrated.md" with { type: "text" };
+import direct from "./direct.md" with { type: "text" };
+import evidenceFirst from "./evidence-first.md" with { type: "text" };
+import explanatory from "./explanatory.md" with { type: "text" };
+import noSlop from "./no-slop.md" with { type: "text" };
+import plainLanguage from "./plain-language.md" with { type: "text" };
+import structured from "./structured.md" with { type: "text" };
+import terminology from "./terminology.md" with { type: "text" };
+import terse from "./terse.md" with { type: "text" };
+
+/** One preset's file name and raw contents, frontmatter included. */
+export interface EmbeddedPreset {
+	/** File name as it appears in this directory, e.g. `direct.md`. */
+	file: string;
+	/** Raw file text — frontmatter and body, exactly as authored. */
+	text: string;
+}
+
+export const EMBEDDED_PRESETS: EmbeddedPreset[] = [
+	{ file: "asd-ste100.md", text: asdSte100 },
+	{ file: "calibrated.md", text: calibrated },
+	{ file: "direct.md", text: direct },
+	{ file: "evidence-first.md", text: evidenceFirst },
+	{ file: "explanatory.md", text: explanatory },
+	{ file: "no-slop.md", text: noSlop },
+	{ file: "plain-language.md", text: plainLanguage },
+	{ file: "structured.md", text: structured },
+	{ file: "terminology.md", text: terminology },
+	{ file: "terse.md", text: terse },
+];

package/src/data/styles/no-slop.md

@@ -0,0 +1,32 @@
+---
+name: no-slop
+axis: modifier
+summary: Banned vocabulary and punctuation tics that mark text as machine-written.
+conflicts:
+---
+
+### No slop
+
+Banned words and phrases. These are not stylistic preferences — they are the
+tells that make text read as generated, and every one of them has a plainer
+replacement:
+
+- **Inflation:** delve, crucial, pivotal, robust, comprehensive, seamless,
+  nuanced, multifaceted, intricate, vibrant, landscape, tapestry, realm,
+  underscore, foster, showcase, leverage (as a verb), utilize.
+- **Connectives:** furthermore, moreover, additionally, notably, importantly.
+  Start the next sentence instead.
+- **Hedged enthusiasm:** "it's worth noting that", "it's important to
+  remember", "as we can see", "at the end of the day".
+- **Empty openers:** "In today's fast-paced world", "When it comes to",
+  "Whether you're a beginner or an expert".
+- **The not-X-but-Y frame** as a reflex: "It's not just a database, it's a
+  platform". Say what it is.
+
+Punctuation and shape:
+
+- No em dashes. Use a comma, a colon, or a full stop.
+- No rule-of-three lists that pad a two-item point to three.
+- No bold on whole sentences. Bold is for the one word the eye should land on.
+- No emoji in code, commit messages, or technical prose unless the project
+  already uses them.

package/src/data/styles/plain-language.md

@@ -0,0 +1,23 @@
+---
+name: plain-language
+axis: modifier
+summary: Gloss jargon on first use, short sentences, active voice, concrete nouns.
+conflicts: terse
+---
+
+### Plain language
+
+- Gloss a term of art the first time it appears, in one clause: "idempotent
+  (running it twice does the same thing as once)". Once per conversation, not
+  once per message.
+- Prefer the concrete noun to the abstraction. "The login page" beats "the
+  authentication surface"; "the file will not open" beats "a resource access
+  issue".
+- Active voice with a named actor. "The migration drops the column", not "the
+  column is dropped".
+- One idea per sentence. If a sentence needs a semicolon to hold together, it
+  is two sentences.
+- Close with what it means for the reader: what they will see, wait for, lose,
+  or be able to do. A technical fact with no consequence attached is trivia.
+- Expand an acronym on first use unless it is more familiar than its
+  expansion — write out "cross-site request forgery", but leave "URL" alone.

package/src/data/styles/structured.md

@@ -0,0 +1,30 @@
+---
+name: structured
+axis: modifier
+summary: When to use a table, a list, a heading, or a paragraph — and when not to.
+conflicts:
+---
+
+### Structure
+
+Match the shape to the content. The wrong container is harder to read than
+plain prose:
+
+| Content | Shape |
+|---|---|
+| Two or more things compared on the same dimensions | table |
+| Steps in order, where order matters | numbered list |
+| Items with no order and no comparison | bullets |
+| One thing explained | paragraph |
+| Reasoning that connects claims | paragraph, not bullets |
+
+- Never bullet a single item. Never build a table with one row or one column.
+- A heading is a promise about what is below it. Do not use headings to break
+  up three sentences.
+- Code identifiers, paths, commands, and literal values go in backticks —
+  every time, including in tables and headings.
+- Reference code as `path/to/file.ts:42`. The line number makes it clickable.
+- Prose carries reasoning; bullets fragment it. If the points depend on each
+  other, write sentences.
+- Length is set by the content. Do not pad a one-line answer into a section,
+  and do not compress a real trade-off into a bullet.

package/src/data/styles/terminology.md

@@ -0,0 +1,28 @@
+---
+name: terminology
+axis: modifier
+summary: Project vocabulary — one name per concept, filled in from the codebase during apply.
+conflicts:
+template: true
+---
+
+### Terminology
+
+One concept, one name, everywhere: code, comments, commit messages, docs, and
+conversation. A concept with two names reads as two concepts.
+
+| Use | Not | Because |
+|---|---|---|
+| <!-- filled during apply --> | | |
+
+Rules that hold regardless of the table above:
+
+- Use the domain's word, not the implementation's. If the business calls it a
+  "booking", the code and the conversation say booking, even where the table
+  is named `reservations`.
+- Do not invent a synonym for a term the codebase already uses. Grep before
+  naming anything new.
+- When the code and the domain disagree on a name, say which you are using and
+  which the reader will see in the file.
+- Keep abbreviations out of names people say out loud. `usr`, `mgr`, and `cfg`
+  save four characters and cost a re-read every time.

package/src/data/styles/terse.md

@@ -0,0 +1,20 @@
+---
+name: terse
+axis: verbosity
+summary: Minimum viable words. No glosses, no framing, no encouragement.
+conflicts: direct, explanatory
+---
+
+### Terse
+
+- Answer in the fewest words that stay correct. One line where one line works.
+- No framing sentences, no summaries of what was just said, no offers of
+  further help.
+- Prefer a fragment to a sentence, a table to prose, a file path to a
+  description of where something lives.
+- Do not explain unless asked. Do not justify a choice unless it is
+  surprising.
+- Omit adjectives that carry no information: "simple", "just", "quick",
+  "straightforward", "basically".
+- Terse is not curt. Answer what was asked completely — brevity comes from
+  cutting padding, never from cutting the answer short.

package/src/main.tsx

@@ -0,0 +1,110 @@
+#!/usr/bin/env bun
+
+// Static import so `bun build --compile` embeds package.json into the binary;
+// a dynamic require("../package.json") is not resolvable inside the bunfs root.
+import pkg from "../package.json";
+import { loadProjectDotenv } from "./services/dotenv.js";
+
+export const VERSION = (pkg as { version: string }).version;
+
+// Note: OpenTUI renderer handles alternate screen buffer automatically
+// No need for manual ANSI escape codes
+//
+// NOTHING in this file may statically import @opentui/* or ./ui/*. `magus
+// hook …` runs on every matching Claude Code tool call, and a static import
+// would load the whole TUI module graph before the hook could answer. The TUI
+// (./tui.js), the router (./cli/router.js, which reaches @opentui through
+// cli/update.ts → ui/theme.ts) and the hook itself are all imported on demand,
+// after the branch that decides which one is needed.
+// Pinned by __tests__/hook-import-policy.test.ts.
+
+/**
+ * `hook` as the first non-theme token → the argv the hook command should see.
+ * Anything else → null.
+ *
+ * A leading `--theme light|dark` (or `--theme=…`) pair is skipped so this
+ * matches the router's own dispatch, which drops the theme tokens before
+ * looking at the command. Deliberately NOT `parseThemeFlag` from the router:
+ * importing that module is the cost this branch exists to avoid, and a hook
+ * has no use for a validated theme.
+ */
+function hookArgv(argv: string[]): string[] | null {
+	let i = 0;
+	while (i < argv.length) {
+		const token = argv[i] as string;
+		if (token === "--theme") {
+			i += 2;
+		} else if (token.startsWith("--theme=")) {
+			i += 1;
+		} else {
+			break;
+		}
+	}
+	return argv[i] === "hook" ? argv.slice(i + 1) : null;
+}
+
+async function main(): Promise<void> {
+	// FIRST, before anything can touch process.env: the theme is read from the
+	// environment magus was started with, never from a project's .env. The
+	// dotenv load below merges into process.env, so the only thing separating
+	// the two is that this line runs before it (pinned by theme-env.test.ts).
+	const { snapshotThemeEnv } = await import("./ui/theme-resolve.js");
+	const themeEnv = snapshotThemeEnv();
+	const args = process.argv.slice(2);
+
+	// Hooks answer here and go no further. This runs BEFORE loadProjectDotenv()
+	// on purpose: a hook must never open a project's .env, because that file is
+	// often a symlink to a 1Password FIFO and reading one BLOCKS until a human
+	// approves it — on every tool call. The hook needs no .env, so it never
+	// touches one.
+	const hookRest = hookArgv(args);
+	if (hookRest !== null) {
+		const { runHookCommand } = await import("./cli/hook.js");
+		process.exit(await runHookCommand(hookRest));
+	}
+
+	// Load the project's .env ourselves. Bun's standalone autoload is compiled OFF
+	// (scripts/build-binaries.ts) because it killed magus outright wherever
+	// .env was a symlink to a FIFO — the shape 1Password uses — exiting 1 with no
+	// output at all. services/dotenv.ts does the same job as an ordinary guarded
+	// read: regular files only, and every failure reported rather than fatal.
+	try {
+		for (const warning of loadProjectDotenv().warnings) {
+			console.warn(`magus: ${warning}`);
+		}
+	} catch (error) {
+		// Belt and braces. loadProjectDotenv is total, but no future edit to it may
+		// ever be allowed to stop magus from starting.
+		console.warn(
+			`magus: .env could not be loaded: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+
+	// Dispatch non-interactive subcommands (claude, update, install, …) and
+	// top-level flags (--version/--help). A bare invocation falls through to
+	// the interactive TUI below.
+	const { route } = await import("./cli/router.js");
+	const outcome = await route(args, VERSION);
+	if (outcome.handled) {
+		process.exit(outcome.exitCode ?? 0);
+	}
+
+	// Both streams must be TTYs for the OSC probe: `magus < file` has a tty
+	// stdout but the reply arrives on stdin, so the probe would wait for nothing.
+	const isInteractive =
+		process.stdin.isTTY === true && process.stdout.isTTY === true;
+
+	// Last possible moment: this is the import that pulls in @opentui and the
+	// whole ui/ tree. Everything above runs without them.
+	const { startTui } = await import("./tui.js");
+	await startTui({
+		theme: outcome.theme,
+		env: themeEnv,
+		isInteractive,
+	});
+}
+
+main().catch((error) => {
+	console.error("Error starting magus:", error);
+	process.exit(1);
+});

package/src/markdown.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Markdown imported as text.
+ *
+ * `import body from "./direct.md" with { type: "text" }` is a Bun bundler
+ * feature — the loader inlines the file as a string literal at build time, so
+ * it survives `bun build --compile`. TypeScript has no idea, hence this
+ * declaration. Without it every preset import in `data/styles/` is an
+ * implicit-any error under `strict`.
+ */
+declare module "*.md" {
+	const contents: string;
+	export default contents;
+}