@monte3l/groundwork 1.0.0-rc.2 → 1.0.0-rc.3

package/dist/palette.d.ts

@@ -0,0 +1,23 @@
+/**
+ * GENERATED FILE -- do not hand-edit. Run `node bin/build-design-tokens.mjs`
+ * to regenerate from design/source/dtcg (the vendored m3l-design tokens).
+ * `--check` (used by `pnpm verify`) fails instead of writing on drift.
+ * Source of truth: design/source/dtcg (DTCG 2025.10). See design/README.md.
+ */
+/** One role's resolved terminal color, per theme -- see term.ts's `paint()`. */
+export interface PaletteRoleColors {
+    readonly success: string;
+    readonly info: string;
+    readonly warning: string;
+    readonly danger: string;
+    readonly accent: string;
+    readonly secondary: string;
+}
+/** {@link PaletteRoleColors} for each theme -- see term.ts's `resolveThemeId()`. */
+export interface Palette {
+    readonly light: PaletteRoleColors;
+    readonly dark: PaletteRoleColors;
+}
+/** The resolved terminal palette, light and dark -- see term.ts's `paint()`. */
+export declare const PALETTE: Palette;
+//# sourceMappingURL=palette.d.ts.map

package/dist/palette.js

@@ -0,0 +1,22 @@
+// SPDX-FileCopyrightText: Copyright the m3l-groundwork contributors
+// SPDX-License-Identifier: MIT
+/** The resolved terminal palette, light and dark -- see term.ts's `paint()`. */
+export const PALETTE = {
+    light: {
+        success: "#086d31",
+        info: "#065da0",
+        warning: "#7d4f0a",
+        danger: "#963730",
+        accent: "#692746",
+        secondary: "#554d50",
+    },
+    dark: {
+        success: "#89d298",
+        info: "#8ac3fe",
+        warning: "#ebb16c",
+        danger: "#fda297",
+        accent: "#d1789e",
+        secondary: "#cdc5c8",
+    },
+};
+//# sourceMappingURL=palette.js.map

package/dist/plugin.d.ts

@@ -1,22 +1,138 @@
+/**
+ * What an install wrote.
+ *
+ * @example
+ * ```ts
+ * import { installCustomizeSkill } from "./plugin.js";
+ *
+ * const { filesWritten } = installCustomizeSkill("/work/app");
+ * filesWritten.at(-1); // ".claude/skills/customize/SKILL.md"
+ * ```
+ */
 export interface InstallPluginResult {
+    /** Paths relative to the project root, in write order (`SKILL.md` last); empty when the destination already held this exact payload. */
     filesWritten: string[];
 }
 /**
  * Installs the skill into `<targetDir>/.claude/skills/customize/`. Used by
- * fresh-bootstrap mode, where the directory is always new.
+ * fresh-bootstrap mode, where the directory is normally new (`--force` may
+ * point it at a non-empty one or an earlier install). An earlier install
+ * that is already byte-identical to this payload is left untouched
+ * (`filesWritten` is empty); otherwise any existing `SKILL.md` is removed
+ * first, then each payload file is removed and recreated. A symlinked
+ * `.claude`, `.claude/skills` or `.claude/skills/customize` is refused, not
+ * routed around.
+ *
+ * @throws `Error` ("could not install the /customize skill ...", raw error
+ * as `cause`) on a missing or unreadable source file, a directory at any
+ * payload name, a payload name or existing file that cannot be `lstat`ed,
+ * or an existing regular file whose read fails with anything other than
+ * `EACCES`/`EPERM` (all before anything is removed or written), a symlinked
+ * or non-directory directory component, any fs failure, or a failed write
+ * -- after removing every file this call wrote. An existing regular file
+ * whose read fails with `EACCES` or `EPERM` is not a failure: it is replaced
+ * like any stale copy. Entries it replaced before the failure are not
+ * restored; the error names them. A failure to locate the default
+ * `sourceDir` is thrown the same way. The message ends, once, by saying to
+ * fix the cause (for a symlink: remove it), then retry
+ * the same command with `--fresh --force` added -- a plain re-run would
+ * adopt the now-non-empty target -- and nowhere in the error chain gives
+ * adopt mode's bare "re-run the CLI" advice.
+ *
+ * @example
+ * ```ts
+ * import { installCustomizeSkill } from "./plugin.js";
+ *
+ * installCustomizeSkill("/work/app").filesWritten.length; // 5
+ * ```
  */
 export declare function installCustomizeSkill(targetDir: string, sourceDir?: string): InstallPluginResult;
 type InstallLocation = "claude" | "groundwork" | "already-present";
+/**
+ * What the adopt-mode install did, and where.
+ *
+ * @example
+ * ```ts
+ * import { installCustomizeSkillGuarded } from "./plugin.js";
+ *
+ * const result = installCustomizeSkillGuarded("/work/app");
+ * if (result.fallbackReason !== undefined) console.log(result.fallbackReason);
+ * ```
+ */
 export interface GuardedInstallResult {
+    /** Paths relative to the project root, in write order (`SKILL.md` last); empty for `"already-present"`. */
     filesWritten: string[];
     location: InstallLocation;
+    /**
+     * Set on every `"groundwork"` result, and only then: why
+     * `.claude/skills/customize/` could not be used, naming the path
+     * responsible -- a symlinked or non-directory component, or the existing
+     * project entry under one of the skill's payload names.
+     */
+    fallbackReason?: string;
+    /**
+     * Set exactly when `fallbackReason` is: `"component"` when a
+     * `.claude`/`.claude/skills`/`.claude/skills/customize` component is a
+     * symlink or not a directory (no project-local copy of the skill exists),
+     * `"entry"` when a project-owned entry sits under one of the skill's
+     * payload names (a project copy exists, and is what a user would replace).
+     */
+    fallbackCause?: "entry" | "component";
 }
 /**
- * Adopt-mode install: purely additive, never overwrites. If the project
- * already has its own `.claude/skills/customize/SKILL.md` and its content
- * differs from what this CLI ships, the skill is written to
- * `.groundwork/customize/` instead -- reported in the adoption report
- * rather than silently overwriting whatever the project already had there.
+ * Adopt-mode install: purely additive, never overwrites or removes a project
+ * entry under `.claude/skills/customize/`.
+ *
+ * - If `.claude`, `.claude/skills` or `.claude/skills/customize` is a
+ *   symlink or not a directory, the skill is written to
+ *   `.groundwork/customize/` instead, `fallbackReason` names that path and
+ *   `fallbackCause` is `"component"` -- the entry (and any link target) is
+ *   left untouched.
+ * - Otherwise, if every payload file already there is a regular file
+ *   matching what this CLI ships byte-for-byte: with all five present the
+ *   result is `"already-present"` (nothing written); with no `SKILL.md` file
+ *   (none at all, or an install interrupted before writing it) the missing
+ *   files are written into `.claude/skills/customize/`, `SKILL.md` last,
+ *   never rewriting or removing the correct ones.
+ * - Anything else under a payload name (a differing file, a regular file
+ *   that cannot be read, a symlink -- dangling or not -- a directory, a
+ *   `SKILL.md` without its data; detected by `lstat`) is kept as the
+ *   project's own: the skill is written to `.groundwork/customize/` instead,
+ *   `fallbackReason` names that entry (saying so when it could not be read)
+ *   and `fallbackCause` is `"entry"`. Adopt mode never guesses at a project
+ *   entry it cannot compare, and the fallback does not guess either: it
+ *   leaves that entry exactly as it was. Claude Code does not load a skill
+ *   from there; the caller must say so.
+ *
+ * Writes into `.claude/skills/customize/` use `"wx"` only, so an entry that
+ * appears there mid-install fails the run (rolled back) rather than being
+ * replaced. Writes into the CLI-owned `.groundwork/customize/` replace that
+ * directory's payload files (any `SKILL.md` removed first, then each file
+ * removed and recreated with `"wx"`); a symlinked `.groundwork` or
+ * `.groundwork/customize`, or a directory at any payload name there, is
+ * refused, never routed around.
+ *
+ * @throws `Error` ("could not install the /customize skill ...", raw error
+ * as `cause`) on a missing or unreadable source file (before anything is
+ * written), a payload name under `.claude/skills/customize/` that cannot be
+ * `lstat`ed or read (a regular file there whose read is refused with
+ * `EACCES`/`EPERM` falls back instead; any other read failure throws before
+ * anything is written), any other fs failure while probing or writing, a
+ * symlinked `.groundwork`/`.groundwork/customize`, or a directory at a
+ * payload name there -- after removing every file this call wrote. A failed
+ * `.groundwork/customize/` install also names why the fallback was taken.
+ * A failure to locate the default `sourceDir` is thrown the same way. The
+ * message ends by
+ * saying to fix the cause (for a symlink: remove it) and re-run the CLI,
+ * once.
+ *
+ * @example
+ * ```ts
+ * import { installCustomizeSkillGuarded } from "./plugin.js";
+ *
+ * const { location } = installCustomizeSkillGuarded("/work/app");
+ * // "claude" | "groundwork" | "already-present"
+ * ```
  */
 export declare function installCustomizeSkillGuarded(targetDir: string, sourceDir?: string): GuardedInstallResult;
 export {};