@openrig/cli 0.3.1 → 0.3.3-rc.0

package/dist/lib/scope/dot-id.d.ts

@@ -0,0 +1,43 @@
+import type { DotId } from "./types.js";
+/** Default project prefix for the OpenRig single-project workspace.
+ *  Multi-project work waits for a real second project (convention §1). */
+export declare const DEFAULT_PROJECT_PREFIX = "OPR";
+/** Parse a dot-ID string into structured parts; returns null when the
+ *  string doesn't conform to the §1 positional grammar. When `tier`
+ *  is supplied, the trailing segments are peeled off into `n` (slice)
+ *  or `n` + `m` (sub-slice). With no tier, all numeric segments are
+ *  returned as `version` for backwards compatibility. */
+export declare function parseDotId(raw: string, tier?: "mission" | "slice" | "sub-slice"): DotId | null;
+/** Depth-based tier discriminator. Per §1 the positional grammar
+ *  is fixed:
+ *    mission   = <PFX>.<ver>           (ver = 2-3 numeric segments;
+ *                                       escape band is exactly 99.0.n)
+ *    slice     = <PFX>.<ver>.<n>       (3-4 numeric segments)
+ *    sub-slice = <PFX>.<ver>.<n>.<m>   (4-5 numeric segments)
+ *  Where a mission shape OVERLAPS with a slice shape (e.g. release
+ *  X.Y mission has 2 segments; release X.Y.Z mission has 3 segments
+ *  which is also the slice shape for release X.Y missions) the tier
+ *  is resolved by depth: mission caps at 3 numeric segments; slice
+ *  always has 3-4; sub-slice has 4-5. Escape band is fully unambiguous
+ *  because §1 fixes both the 99 marker AND the 0 segment that follows. */
+export declare function isMissionDotId(raw: unknown): boolean;
+export declare function isSliceDotId(raw: unknown): boolean;
+/** Render a DotId back to its canonical dot-string. */
+export declare function formatDotId(id: DotId): string;
+/** Compose a slice ID by appending an ordinal to a parent mission ID. */
+export declare function sliceIdFromMission(missionId: string, n: number): string;
+/** Infer the (project, version) pair from a mission folder name when
+ *  no explicit id is supplied. Release missions use their semver; any
+ *  other name falls into the escape band where the caller supplies the
+ *  next ordinal via the second arg. */
+export declare function inferMissionDotId(missionFolderName: string, escapeBandOrdinal: number | null, projectPrefix?: string): string;
+/** Pick the next escape-band ordinal by scanning peer mission IDs.
+ *  Looks for `<PFX>.99.0.<m>` shapes and returns max(m)+1, starting
+ *  at 1 when no peer exists. */
+export declare function nextEscapeBandOrdinal(existingIds: ReadonlyArray<string | null>, projectPrefix?: string): number;
+/** Does this candidate string parse as a valid §1 dot-ID at ANY
+ *  tier? Prefer the tier-specific isMissionDotId/isSliceDotId at use
+ *  sites where the tier is known — depth alone doesn't disambiguate
+ *  mission vs slice for release IDs with overlapping shapes. */
+export declare function isConformantDotId(raw: unknown): boolean;
+//# sourceMappingURL=dot-id.d.ts.map

package/dist/lib/scope/dot-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dot-id.d.ts","sourceRoot":"","sources":["../../../src/lib/scope/dot-id.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC;0EAC0E;AAC1E,eAAO,MAAM,sBAAsB,QAAQ,CAAC;AAS5C;;;;yDAIyD;AACzD,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,WAAW,GACvC,KAAK,GAAG,IAAI,CAyBd;AAkBD;;;;;;;;;;;0EAW0E;AAC1E,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAKpD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAQlD;AAED,uDAAuD;AACvD,wBAAgB,WAAW,CAAC,EAAE,EAAE,KAAK,GAAG,MAAM,CAK7C;AAED,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED;;;uCAGuC;AACvC,wBAAgB,iBAAiB,CAC/B,iBAAiB,EAAE,MAAM,EACzB,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,aAAa,GAAE,MAA+B,GAC7C,MAAM,CAaR;AAED;;gCAEgC;AAChC,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,aAAa,CAAC,MAAM,GAAG,IAAI,CAAC,EACzC,aAAa,GAAE,MAA+B,GAC7C,MAAM,CAWR;AAED;;;gEAGgE;AAChE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEvD"}

package/dist/lib/scope/dot-id.js

@@ -0,0 +1,165 @@
+// release-0.3.2 slice 12 — dot-ID grammar per
+// `openrig-work/conventions/scope-and-versioning/README.md` §1.
+//
+// Grammar (v0 single-project):
+//   project  = <PFX>            (2-3 letter; v0 hardcodes "OPR")
+//   mission  = <PFX>.<ver>
+//   slice    = <PFX>.<ver>.<n>
+//   sub      = <PFX>.<ver>.<n>.<m>
+//
+// Version inference from mission folder name:
+//   release-X.Y[.Z]     → "X.Y[.Z]"         (release train)
+//   anything else       → "99.0.<m>" escape band (uniform-numeric;
+//                          NO alpha — convention §1 explicit)
+//
+// The escape-band <m> is assigned by scanning peer non-release missions
+// for an existing id and picking max+1. Releases keep their semver.
+import { ScopeCliError } from "./types.js";
+/** Default project prefix for the OpenRig single-project workspace.
+ *  Multi-project work waits for a real second project (convention §1). */
+export const DEFAULT_PROJECT_PREFIX = "OPR";
+const RELEASE_NAME_RE = /^release-(\d+\.\d+(?:\.\d+)?)$/;
+// Strict positional grammar: every segment is a number except for the
+// 2-3 letter project prefix at position 0. Accepts 2-5 numeric
+// segments after the prefix (mission has 2-3, slice has 3-4, sub-slice
+// has 4-5). Tier-aware parse helpers below split version/n/m correctly.
+const DOT_ID_RE = /^([A-Z]{2,3})\.(\d+(?:\.\d+){1,4})$/;
+/** Parse a dot-ID string into structured parts; returns null when the
+ *  string doesn't conform to the §1 positional grammar. When `tier`
+ *  is supplied, the trailing segments are peeled off into `n` (slice)
+ *  or `n` + `m` (sub-slice). With no tier, all numeric segments are
+ *  returned as `version` for backwards compatibility. */
+export function parseDotId(raw, tier) {
+    if (typeof raw !== "string")
+        return null;
+    const trimmed = raw.trim();
+    const m = DOT_ID_RE.exec(trimmed);
+    if (!m)
+        return null;
+    const project = m[1];
+    const segments = m[2].split(".");
+    if (!tier) {
+        return { project, version: segments.join("."), n: undefined, m: undefined };
+    }
+    if (tier === "mission") {
+        return { project, version: segments.join("."), n: undefined, m: undefined };
+    }
+    if (tier === "slice") {
+        if (segments.length < 3)
+            return null; // slice = ver(>=2) + n
+        const verSegs = segments.slice(0, -1);
+        const nSeg = segments[segments.length - 1];
+        return { project, version: verSegs.join("."), n: Number(nSeg), m: undefined };
+    }
+    // sub-slice
+    if (segments.length < 4)
+        return null;
+    const verSegs = segments.slice(0, -2);
+    const nSeg = segments[segments.length - 2];
+    const mSeg = segments[segments.length - 1];
+    return { project, version: verSegs.join("."), n: Number(nSeg), m: Number(mSeg) };
+}
+/** Validate a mission-ver segments array against the §1 escape-band
+ *  rule. The convention defines the non-release escape band as
+ *  `<PFX>.99.0.<n>` — the `0` after `99` is FIXED. A version like
+ *  `99.7.8` does NOT conform. Shared between isMissionDotId and the
+ *  parent-version check inside isSliceDotId so both surfaces stay in
+ *  lockstep. */
+function isValidMissionVerSegments(segs) {
+    if (segs.length < 2 || segs.length > 3)
+        return false;
+    if (segs[0] === "99") {
+        // Escape band: exactly [99, "0", "<ordinal>"]. The `0` segment is
+        // fixed; `<ordinal>` must be a non-empty numeric string.
+        return segs.length === 3 && segs[1] === "0" && /^\d+$/.test(segs[2] ?? "");
+    }
+    return true;
+}
+/** Depth-based tier discriminator. Per §1 the positional grammar
+ *  is fixed:
+ *    mission   = <PFX>.<ver>           (ver = 2-3 numeric segments;
+ *                                       escape band is exactly 99.0.n)
+ *    slice     = <PFX>.<ver>.<n>       (3-4 numeric segments)
+ *    sub-slice = <PFX>.<ver>.<n>.<m>   (4-5 numeric segments)
+ *  Where a mission shape OVERLAPS with a slice shape (e.g. release
+ *  X.Y mission has 2 segments; release X.Y.Z mission has 3 segments
+ *  which is also the slice shape for release X.Y missions) the tier
+ *  is resolved by depth: mission caps at 3 numeric segments; slice
+ *  always has 3-4; sub-slice has 4-5. Escape band is fully unambiguous
+ *  because §1 fixes both the 99 marker AND the 0 segment that follows. */
+export function isMissionDotId(raw) {
+    if (typeof raw !== "string")
+        return false;
+    const parsed = parseDotId(raw, "mission");
+    if (!parsed)
+        return false;
+    return isValidMissionVerSegments(parsed.version.split("."));
+}
+export function isSliceDotId(raw) {
+    if (typeof raw !== "string")
+        return false;
+    const parsed = parseDotId(raw, "slice");
+    if (!parsed)
+        return false;
+    // Slice = mission-ver + 1 ordinal. Parent ver must itself be a
+    // valid mission shape (including the escape-band exact-[99.0.n]
+    // rule — a parent like 99.7.8 is not a real mission).
+    return isValidMissionVerSegments(parsed.version.split("."));
+}
+/** Render a DotId back to its canonical dot-string. */
+export function formatDotId(id) {
+    const parts = [id.project, id.version];
+    if (id.n !== undefined)
+        parts.push(String(id.n));
+    if (id.m !== undefined)
+        parts.push(String(id.m));
+    return parts.join(".");
+}
+/** Compose a slice ID by appending an ordinal to a parent mission ID. */
+export function sliceIdFromMission(missionId, n) {
+    return `${missionId}.${n}`;
+}
+/** Infer the (project, version) pair from a mission folder name when
+ *  no explicit id is supplied. Release missions use their semver; any
+ *  other name falls into the escape band where the caller supplies the
+ *  next ordinal via the second arg. */
+export function inferMissionDotId(missionFolderName, escapeBandOrdinal, projectPrefix = DEFAULT_PROJECT_PREFIX) {
+    const releaseMatch = RELEASE_NAME_RE.exec(missionFolderName);
+    if (releaseMatch) {
+        return `${projectPrefix}.${releaseMatch[1]}`;
+    }
+    if (escapeBandOrdinal === null) {
+        throw new ScopeCliError({
+            fact: `Mission "${missionFolderName}" doesn't match the release-X.Y[.Z] pattern and no escape-band ordinal was supplied.`,
+            consequence: "No dot-ID could be inferred for this mission.",
+            action: "Pass an explicit ordinal, or rename the mission to release-X.Y.Z, or supply --id on the CLI.",
+        });
+    }
+    return `${projectPrefix}.99.0.${escapeBandOrdinal}`;
+}
+/** Pick the next escape-band ordinal by scanning peer mission IDs.
+ *  Looks for `<PFX>.99.0.<m>` shapes and returns max(m)+1, starting
+ *  at 1 when no peer exists. */
+export function nextEscapeBandOrdinal(existingIds, projectPrefix = DEFAULT_PROJECT_PREFIX) {
+    let max = 0;
+    const re = new RegExp(`^${projectPrefix}\\.99\\.0\\.(\\d+)$`);
+    for (const id of existingIds) {
+        if (!id)
+            continue;
+        const m = re.exec(id);
+        if (!m)
+            continue;
+        const n = Number(m[1]);
+        if (Number.isFinite(n) && n > max)
+            max = n;
+    }
+    return max + 1;
+}
+/** Does this candidate string parse as a valid §1 dot-ID at ANY
+ *  tier? Prefer the tier-specific isMissionDotId/isSliceDotId at use
+ *  sites where the tier is known — depth alone doesn't disambiguate
+ *  mission vs slice for release IDs with overlapping shapes. */
+export function isConformantDotId(raw) {
+    return typeof raw === "string" && parseDotId(raw) !== null;
+}
+//# sourceMappingURL=dot-id.js.map

package/dist/lib/scope/dot-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dot-id.js","sourceRoot":"","sources":["../../../src/lib/scope/dot-id.ts"],"names":[],"mappings":"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"}

package/dist/lib/scope/scope-fs.d.ts

@@ -0,0 +1,79 @@
+import type { MissionInfo, SliceInfo, SliceState } from "./types.js";
+import { DEFAULT_PROJECT_PREFIX } from "./dot-id.js";
+/** Split a markdown file into [frontmatter, body]. Returns `[{}, content]`
+ *  when no frontmatter delimiter is present. */
+export declare function splitFrontmatter(content: string): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};
+/** Re-stitch frontmatter + body into a single markdown string. */
+export declare function joinFrontmatter(frontmatter: Record<string, unknown>, body: string): string;
+/** Read + parse frontmatter from a markdown file. Returns `{}` if the
+ *  file is missing OR has no frontmatter (graceful for placeholder
+ *  missions that pre-date the convention). */
+export declare function readFrontmatter(absPath: string): Record<string, unknown>;
+/** Update specific keys in a markdown file's frontmatter. Existing
+ *  unknown keys are preserved. Generates minimal frontmatter when
+ *  absent. */
+export declare function updateFrontmatter(absPath: string, updates: Record<string, unknown>): void;
+/** Locate the missions root for the working substrate. Resolution
+ *  order:
+ *    1. Explicit override (env or arg)
+ *    2. $OPENRIG_WORK_ROOT/missions
+ *    3. Search up from cwd for a `missions/` folder
+ */
+export declare function resolveMissionsRoot(opts?: {
+    override?: string | null;
+    cwd?: string;
+}): string;
+/** List mission folders under the missions root. A mission is any
+ *  top-level folder containing a README.md (per IMPLEMENTATION-PRD
+ *  §2.1 / HG-8). Directories without a README.md are skipped — they
+ *  represent scratch/junk, not declared missions. */
+export declare function listMissions(missionsRoot: string): MissionInfo[];
+/** Resolve a mission by name OR path relative to the missions root.
+ *  Throws ScopeCliError on miss OR when the directory exists but
+ *  lacks a README.md (consistent with listMissions' README gate per
+ *  PRD §2.1 / HG-8 — README-less dirs are scratch/junk, not declared
+ *  missions, so mutation commands must not silently target them). */
+export declare function findMission(missionsRoot: string, identifier: string): MissionInfo;
+export declare function listSlices(mission: MissionInfo, state: SliceState): SliceInfo[];
+/** Resolve a slice path (absolute, relative-to-substrate, or
+ *  relative-to-mission) into a SliceInfo. */
+export declare function findSlice(missionsRoot: string, slicePath: string, hintMission?: string | null): SliceInfo;
+/** Find the next available NN for a mission's slices/ folder. Scans
+ *  BOTH slices/ AND closed/ so numbers are never reused (§3.2). */
+export declare function nextSliceNN(missionAbsPath: string): number;
+/** Mint or read the dot-ID for a mission. If the mission's README has
+ *  an `id:` field, return it. Otherwise infer from the folder name
+ *  (release-X.Y.Z → OPR.X.Y.Z; otherwise escape band). */
+export declare function ensureMissionId(mission: MissionInfo, missionsRoot: string): string;
+/** Same as ensureMissionId, but ALSO writes the inferred id back into
+ *  the mission's README frontmatter when it was absent. Use this at
+ *  every site that mints a child id (slice create / ship / move target)
+ *  — per the convention's lazy-adoption rule: when a child is created
+ *  under a pre-existing parent with no id, assign the parent's id
+ *  on-demand at the same time. Narrow, single-parent, create-triggered;
+ *  never mass-migration. */
+export declare function ensureMissionIdPersisted(mission: MissionInfo, missionsRoot: string): string;
+/** Return the git toplevel for a path, or null if not inside a repo. */
+export declare function gitTopLevel(absPath: string): string | null;
+/** Refuse to move a path with uncommitted local changes. Catches the
+ *  "dirty working tree" risk in §11.1 / §3.4 — `git mv` would silently
+ *  carry along the user's in-progress edits. */
+export declare function assertCleanWorkingTree(repoRoot: string, relPath: string): void;
+/** Move a directory using `git mv` when inside a repo; fall back to
+ *  `fs.renameSync` with a warning when not. Returns true if git was
+ *  used. */
+export declare function moveSlice(srcAbs: string, destAbs: string, opts?: {
+    /** Stage the move (default true). git mv stages by default; we
+     *  preserve that semantic. */
+    commit?: boolean;
+}): {
+    usedGit: boolean;
+    repoRoot: string | null;
+};
+export declare function todayDateISO(): string;
+export declare function pad2(n: number): string;
+export { DEFAULT_PROJECT_PREFIX };
+//# sourceMappingURL=scope-fs.d.ts.map

package/dist/lib/scope/scope-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-fs.d.ts","sourceRoot":"","sources":["../../../src/lib/scope/scope-fs.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACT,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EAGvB,MAAM,aAAa,CAAC;AASrB;gDACgD;AAChD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IACjD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd,CAgBA;AAaD,kEAAkE;AAClE,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,IAAI,EAAE,MAAM,GACX,MAAM,CAIR;AAED;;8CAE8C;AAC9C,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMxE;AAED;;cAEc;AACd,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAKN;AAMD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,GAAE;IACxC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACT,GAAG,MAAM,CAsBd;AAED;;;qDAGqD;AACrD,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,WAAW,EAAE,CA6BhE;AAcD;;;;qEAIqE;AACrE,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,WAAW,CAuBjF;AAqBD,wBAAgB,UAAU,CACxB,OAAO,EAAE,WAAW,EACpB,KAAK,EAAE,UAAU,GAChB,SAAS,EAAE,CA8Bb;AAyBD;6CAC6C;AAC7C,wBAAgB,SAAS,CACvB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAC1B,SAAS,CAiCX;AAeD;mEACmE;AACnE,wBAAgB,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAc1D;AAED;;0DAE0D;AAC1D,wBAAgB,eAAe,CAC7B,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,MAAM,GACnB,MAAM,CAYR;AAED;;;;;;4BAM4B;AAC5B,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,MAAM,GACnB,MAAM,CASR;AAMD,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW1D;AAED;;gDAEgD;AAChD,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAsB9E;AAED;;YAEY;AACZ,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE;IAC/D;kCAC8B;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;CACb,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CA6CrD;AAMD,wBAAgB,YAAY,IAAI,MAAM,CAMrC;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEtC;AAED,OAAO,EAAE,sBAAsB,EAAE,CAAC"}