strikethroo 3.14.3 → 3.16.0

package/dist/profiles.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Profile Package Contract and Import Preparation
+ *
+ * Defines the manifest schema (`profile.yaml`) and on-disk surface every
+ * profile package — local folder or cloned repository — must satisfy, and
+ * owns the import steps that run before any workspace mutation: source
+ * resolution (local folder / GitHub shorthand / git URL), shallow-clone
+ * materialization of remote profiles, contract validation, and staging of
+ * the effective template tree (shipped defaults + profile overlay).
+ *
+ * Validation is side-effect-free: it only reads the package directory.
+ * Materialization and staging write only to temp directories under the OS
+ * temp root, and every temp directory is removed on every exit path.
+ */
+/**
+ * Manifest schema version this CLI build understands.
+ *
+ * Profiles live in external repositories the CLI can never migrate, so a
+ * manifest declaring a different version is refused with a message naming
+ * both versions and the upgrade direction.
+ */
+export declare const PROFILE_MANIFEST_SCHEMA_VERSION = 1;
+/**
+ * A single entry in a manifest's `requires` or `recommends` list.
+ *
+ * Strictly informational: printed during import, never probed, executed,
+ * or installed.
+ */
+export interface ProfileRequirement {
+    /**
+     * What kind of prerequisite this is
+     */
+    kind: 'skill' | 'tool';
+    /**
+     * Name of the required skill or tool
+     */
+    name: string;
+    /**
+     * Optional human-facing installation hint
+     */
+    install?: string;
+}
+/**
+ * Parsed `profile.yaml` manifest
+ */
+export interface ProfileManifest {
+    /**
+     * Manifest format version (must equal PROFILE_MANIFEST_SCHEMA_VERSION)
+     */
+    schema_version: number;
+    /**
+     * Profile identity (kebab-case), echoed at import and recorded in provenance
+     */
+    name: string;
+    /**
+     * One-line summary shown during init
+     */
+    description: string;
+    /**
+     * Long-form statement of what the profile is tuned for
+     */
+    purpose?: string;
+    /**
+     * Free-form discovery/labeling tags
+     */
+    tags?: string[];
+    /**
+     * Hard prerequisites without which the profile's hooks/config malfunction
+     */
+    requires?: ProfileRequirement[];
+    /**
+     * Soft pairings that complement the profile
+     */
+    recommends?: ProfileRequirement[];
+    /**
+     * Attribution
+     */
+    author?: string;
+}
+/**
+ * Validate a profile package directory against the contract.
+ *
+ * Checks, in order: `profile.yaml` exists and parses as a YAML mapping, the
+ * manifest fields satisfy the schema, and the `config/` surface contains only
+ * allowed files. Top-level entries other than `profile.yaml` and `config/`
+ * are ignored (a repository may carry `README.md`, `.git`, etc.).
+ *
+ * @param profileDir - Absolute or relative path to the package root
+ * @returns The parsed manifest on success
+ * @throws ProfileError naming the offending field or file on any violation
+ */
+export declare function validateProfilePackage(profileDir: string): Promise<ProfileManifest>;
+/**
+ * A `--profile` value resolved to its concrete source
+ */
+export interface ResolvedProfileSource {
+    /**
+     * Whether the profile is read in place ('local') or cloned via git ('git')
+     */
+    kind: 'local' | 'git';
+    /**
+     * Absolute local package path ('local') or git clone URL ('git')
+     */
+    location: string;
+}
+/**
+ * Result of preparing a profile import, ready for the init copy machinery
+ */
+export interface PreparedProfileImport {
+    /**
+     * Temp directory mirroring `templates/strikethroo/` with the profile's
+     * `config/` files overlaid — the effective source tree for init
+     */
+    stagingDir: string;
+    /**
+     * The profile's validated manifest
+     */
+    manifest: ProfileManifest;
+    /**
+     * Resolved provenance: the clone URL or the absolute local package path
+     */
+    source: string;
+    /**
+     * Removes every temp directory this import created; safe to call more
+     * than once and tolerant of already-removed paths
+     */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Resolve a `--profile` value to its source.
+ *
+ * Resolution order is contractual: (a) the value names an existing directory
+ * on disk → local package folder; (b) the value matches the GitHub
+ * `<user>/<repo-name>` shorthand → expanded to the canonical GitHub clone
+ * URL; (c) otherwise → treated verbatim as a git URL (covers GitLab, ssh
+ * URLs, and any git host). The existing-path check runs first, so a relative
+ * local path that happens to look like `user/repo` resolves as the folder.
+ *
+ * @param value - The raw `--profile` argument
+ * @returns The resolved source kind and location
+ * @throws ProfileError when the value names an existing non-directory path
+ */
+export declare function resolveProfileSource(value: string): Promise<ResolvedProfileSource>;
+/**
+ * Resolve, materialize, validate, and stage a profile for import.
+ *
+ * Steps, in order: resolve the source; shallow-clone remote profiles into a
+ * temp directory (local folders are read in place); validate the package
+ * against the contract BEFORE any staging, so an invalid profile never
+ * produces a staging tree; copy the shipped template tree into a temp
+ * staging directory and overlay the profile's `config/` files.
+ *
+ * Every temp directory is removed on every failure path before the error is
+ * rethrown. On success the caller receives `cleanup` and must invoke it once
+ * the copy machinery has consumed `stagingDir`.
+ *
+ * @param profileValue - The raw `--profile` argument
+ * @param shippedTemplateDir - Path to the shipped `templates/strikethroo/` tree
+ * @returns The staging directory, validated manifest, resolved source, and cleanup
+ * @throws ProfileError on resolution, clone, validation, or staging failure
+ */
+export declare function prepareProfileImport(profileValue: string, shippedTemplateDir: string): Promise<PreparedProfileImport>;
+//# sourceMappingURL=profiles.d.ts.map

package/dist/profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../src/profiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAYH;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,IAAI,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;OAEG;IACH,QAAQ,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAChC;;OAEG;IACH,UAAU,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAClC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAIzF;AAaD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,IAAI,EAAE,OAAO,GAAG,KAAK,CAAC;IACtB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,QAAQ,EAAE,eAAe,CAAC;IAC1B;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA6BxF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,oBAAoB,CACxC,YAAY,EAAE,MAAM,EACpB,kBAAkB,EAAE,MAAM,GACzB,OAAO,CAAC,qBAAqB,CAAC,CAsBhC"}