@ahood/cli 0.11.0 → 0.12.1

package/dist/project-remote.js

@@ -0,0 +1,80 @@
+// Git remotes for project guides (ahood-cli#185): reading this repository's
+// origin, and normalizing a remote to the `host/owner/repo` form the ahood
+// server stores and matches on. normalizeProjectRemote is a line-for-line port
+// of the server's lib/projects/normalize-project-remote.ts (ahood#778) -- the
+// two must agree, or `project init` writes a remote the lookup never matches.
+// tests/project-remote.test.ts runs the server's own test table against it.
+import { execFileSync } from "node:child_process";
+const HOST_LABEL = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const PATH_SEGMENT = /^[a-z0-9._-]+$/;
+const ALLOWED_SCHEMES = ["https", "http", "ssh", "git"];
+const MAX_PROJECT_REMOTE_LENGTH = 255;
+const MAX_PATH_SEGMENTS = 8;
+// Never echoes the input back: a rejected remote can still carry a
+// credential (`https://user:token@...`).
+const INVALID = {
+    ok: false,
+    reason: "not a git remote; expected host/owner/repo, e.g. github.com/owner/repo",
+};
+// Strips the scheme, any userinfo (`user:token@`), the port, a trailing
+// `.git` and trailing slashes, then lowercases everything.
+export function normalizeProjectRemote(raw) {
+    const input = raw.trim();
+    if (!input || input.length > MAX_PROJECT_REMOTE_LENGTH)
+        return INVALID;
+    if (/[\s?#\\]/.test(input))
+        return INVALID;
+    let rest;
+    const scheme = input.match(/^([a-z][a-z0-9+.-]*):\/\//i);
+    if (scheme) {
+        if (!ALLOWED_SCHEMES.includes(scheme[1].toLowerCase()))
+            return INVALID;
+        rest = input.slice(scheme[0].length);
+    }
+    else {
+        // scp-like form: [user@]host:path, where the path does not start with "/".
+        const scp = input.match(/^(?:[^@/:]+@)?([^@/:]+):(?!\/)(.+)$/);
+        rest = scp ? `${scp[1]}/${scp[2]}` : input;
+    }
+    const slash = rest.indexOf("/");
+    if (slash <= 0)
+        return INVALID;
+    let host = rest.slice(0, slash);
+    const at = host.lastIndexOf("@");
+    if (at !== -1)
+        host = host.slice(at + 1);
+    host = host.replace(/:\d+$/, "").toLowerCase();
+    const labels = host.split(".");
+    if (labels.length < 2 || !labels.every((label) => HOST_LABEL.test(label)))
+        return INVALID;
+    const path = rest
+        .slice(slash + 1)
+        .replace(/\/+$/, "")
+        .replace(/\.git$/i, "")
+        .replace(/\/+$/, "")
+        .toLowerCase();
+    const segments = path.split("/");
+    if (segments.length < 2 || segments.length > MAX_PATH_SEGMENTS)
+        return INVALID;
+    if (!segments.every((s) => s !== "." && s !== ".." && PATH_SEGMENT.test(s)))
+        return INVALID;
+    return { ok: true, value: `${host}/${segments.join("/")}` };
+}
+// The current repository's origin, normalized, or undefined when there is no
+// git, no repository, no origin, or an origin that is not a shareable remote.
+// The raw URL never leaves this function: it can carry a token.
+export function detectProjectRemote() {
+    let raw;
+    try {
+        raw = execFileSync("git", ["remote", "get-url", "origin"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5000,
+        });
+    }
+    catch {
+        return undefined;
+    }
+    const normalized = normalizeProjectRemote(raw);
+    return normalized.ok ? normalized.value : undefined;
+}

package/dist/spec.js

@@ -129,3 +129,12 @@ export function docPath(owner, doc) {
     validateSegment(doc, "skill", spec);
     return join(DOCS_ROOT, `${owner}@${doc}.md`);
 }
+// A project guide installs to one fixed path per repository (ahood-cli#185),
+// beside CLAUDE.md/AGENTS.md rather than inside them, so ahood never edits a
+// file the user owns. Being shared, the path is claimed by exactly one pin:
+// add.ts refuses a second guide while another is pinned.
+export const PROJECT_GUIDE_PATH = join(".claude", "project.md");
+// Where a pinned-file kind's install lives (kind-info.ts PINNED_FILE_KINDS).
+export function pinnedFilePath(kind, owner, slug) {
+    return kind === "doc" ? docPath(owner, slug) : PROJECT_GUIDE_PATH;
+}

package/dist/useme/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ahood
-description: How to use the ahood CLI (@ahood/cli), the registry for reusable AI-agent skills, subagent definitions (AGENT.md), MCP server manifests (server.json), and docs (DOC.md). Load BEFORE running any ahood command; before writing a non-trivial reusable skill, subagent, or MCP integration from scratch (search the registry first); when installing, updating, removing, publishing, sharing, or unpublishing one; when wiring ahood into an MCP host; or when setting up headless/CI access with AHOOD_TOKEN. Triggers - ahood, skill registry, is there a skill for this, install a skill, install an agent, add an MCP server, read a doc, publish a skill, ahood mcp, ahood doc, AHOOD_TOKEN.
+description: How to use the ahood CLI (@ahood/cli), the registry for reusable AI-agent skills, subagent definitions (AGENT.md), MCP server manifests (server.json), docs (DOC.md), and project guides (PROJECT.md). Load BEFORE running any ahood command; before writing a non-trivial reusable skill, subagent, or MCP integration from scratch (search the registry first); when installing, updating, removing, publishing, sharing, or unpublishing one; when wiring ahood into an MCP host; or when setting up headless/CI access with AHOOD_TOKEN. Triggers - ahood, skill registry, is there a skill for this, install a skill, install an agent, add an MCP server, read a doc, project guide, publish a skill, ahood mcp, ahood doc, ahood project, AHOOD_TOKEN.
 ---
 
 # ahood
@@ -13,7 +13,7 @@ and only moves when someone runs an update.
 This guide ships inside the CLI itself (`ahood help useme`), so it matches the installed
 version (`ahood --version`). It needs no login or network to print.
 
-## Four kinds, four command groups
+## Five kinds, five command groups
 
 | Kind | Root file | Installs to | Commands |
 |---|---|---|---|
@@ -21,23 +21,29 @@ version (`ahood --version`). It needs no login or network to print.
 | agent | `AGENT.md` | `.claude/agents/<owner>@<agent>.md` | `ahood agent <verb>` |
 | mcp | `server.json` | an entry merged into `.mcp.json` | `ahood mcp <verb>` |
 | doc | `DOC.md` | `.claude/docs/<owner>@<doc>.md` | `ahood doc <verb>` |
+| project | `PROJECT.md` | `.claude/project.md` (one per repository) | `ahood project <verb>` |
 
-All four groups take the same verbs: `search`, `list`, `view`/`show`, `read`, `versions`,
+All five groups take the same verbs: `search`, `list`, `view`/`show`, `read`, `versions`,
 `diff`, `add`, `update`, `outdated`, `remove`, `edit`, `unpublish`, `star`, `unstar`,
 `share`, `unshare`, `init`, `publish`.
 
-- `ahood agent <verb>`, `ahood mcp <verb>` and `ahood doc <verb>` act on their own kind only.
+- `ahood agent <verb>`, `ahood mcp <verb>`, `ahood doc <verb>` and `ahood project <verb>` act on their own kind only.
   A target of another kind is refused (exit 2) before anything is downloaded, prompted for,
   written, or sent, and the error names the kind it found and the right command.
 - `ahood skill <verb>` is the **legacy, cross-kind** group in this CLI release: `skill search`
   and `skill list` include every kind, and `skill add`/`skill update` install whatever kind
-  they resolve, except a doc: `skill add` refuses one and points at `ahood doc add`.
-  Add `--kind skill` (or `agent`, `mcp`, `doc`) to any verb to scope it to one kind;
+  they resolve, except a doc or project guide: `skill add` refuses one and points at
+  `ahood doc add` / `ahood project add`.
+  Add `--kind skill` (or `agent`, `mcp`, `doc`, `project`) to any verb to scope it to one kind;
   `--kind all` spells out the legacy behavior. Prefer the kind-specific form in anything new --
   a future major version makes `ahood skill` skills-only.
 - A doc is a documentation page. `ahood doc read alice/setup-guide` prints it without
   installing anything; `ahood doc add alice/setup-guide` saves it as one pinned file under
   `.claude/docs/`, which `ahood doc update` and `ahood doc remove` manage like any other pin.
+- A project guide is how to work in one repository: conventions, verification, traps. Run bare
+  `ahood project` inside a repository to list the guides naming its git remote;
+  `ahood project add alice/acme-api` saves one to `.claude/project.md` (pinned, one per
+  repository) and never touches `CLAUDE.md` or `AGENTS.md` -- point those at it yourself.
 
 ## Find, inspect, then install
 
@@ -87,7 +93,7 @@ ahood skill update --dry-run --json    # preview, machine-readable
 ahood agent remove alice/code-reviewer # local uninstall; prompts unless --yes
 ```
 
-With no target, `agent`/`mcp`/`doc` `update` and `outdated` consider only installed pins of that
+With no target, `agent`/`mcp`/`doc`/`project` `update` and `outdated` consider only installed pins of that
 kind; the legacy `skill update` covers every pin. Updates only affect the current project.
 An `.mcp.json` entry you edited by hand is refused rather than overwritten.
 
@@ -100,13 +106,14 @@ ahood skill init pdf-tools             # ./pdf-tools/SKILL.md
 ahood agent init code-reviewer         # ./code-reviewer/AGENT.md
 ahood mcp init github-server           # ./github-server/server.json (placeholder URL)
 ahood doc init setup-guide             # ./setup-guide/DOC.md
+ahood project init acme-api            # ./acme-api/PROJECT.md, `project:` filled from git origin
 
 ahood agent publish alice/code-reviewer@1.0.0 --path code-reviewer --name "Code Reviewer"
 ahood skill publish alice/pdf-tools@1.1.0 --path pdf-tools --changelog "Adds split"
 ```
 
 - `--name` is required only on the first publish, which creates the entry under your
-  account. `agent publish`/`mcp publish`/`doc publish` imply the kind and refuse a contradictory `--kind`
+  account. `agent publish`/`mcp publish`/`doc publish`/`project publish` imply the kind and refuse a contradictory `--kind`
   or an existing entry of another kind before uploading anything.
 - **New entries are private.** Make one discoverable explicitly:
   `ahood skill edit alice/pdf-tools --visibility public`.
@@ -153,7 +160,7 @@ ahood skill publish alice/pdf-tools@1.1.0 --path pdf-tools --changelog "Adds spl
 3. **The hosted registry MCP endpoint**, `https://www.ahood.dev/api/mcp`: Streamable HTTP,
    stateless (POST only), `Authorization: Bearer <token>`. It has write tools too:
    `search_skills`, `get_skill`, `fetch_skill`, `read_skill`, `list_skill_versions`,
-   `list_my_skills`, `search_collections`, `get_collection`, `create_skill`, `update_skill`,
+   `list_my_skills`, `search_collections`, `get_collection`, `get_project_guide`, `create_skill`, `update_skill`,
    `report_skill`, `delete_skill`, `yank_version`, and snap tools (`create_snap`,
    `list_snaps`, `get_snap`, `set_snap_tags`, `delete_snap`, `share_snap`, `unshare_snap`).
    A client that opens with a legacy-SSE `GET` gets a 405 -- use a Streamable HTTP client.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahood/cli",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "description": "CLI for ahood, a registry for installing and publishing Claude Code skills.",
   "license": "MIT",
   "homepage": "https://github.com/AlexKay28/ahood-cli",