jg-plans 0.0.0-stage → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.1.2 — documentation and examples
+
+- Complete the canonical documentation and consumer integration recipes alongside the visual example explorer, original-source downloads, and verified package availability presentation.
+- Keep protocol 0.1 provisional and the reference library/CLI behavior unchanged.
+
+## 0.1.1 — trusted publishing validation
+
+- Prepare the first automated release after the manual 0.1.0 bootstrap, using the qualified archive and registry/provenance verification workflow.
+- Keep protocol 0.1 and the reference API/CLI behavior from the initial preview.
+
+## 0.1.0 — development preview
+
+- Introduce provisional protocol 0.1 for Markdown plans with optional milestones, extensible metadata, and ordinary user edits/deletion.
+- Add tolerant parsing, selected-directory inspection, and optional conformance checking with structured diagnostics.
+- Add exclusive plan creation and conservative metadata/marker updates that preserve unrelated bytes; document caller serialization and unsupported edits.
+- Ship the library declarations, four-command CLI, canonical public references, synthetic examples, and a runnable installed-consumer example.
+- Qualify an exact archive across the supported Node/OS matrix, with checksum receipts, registry/content checks, OIDC publishing readiness, and an isolated owner bootstrap runbook.
+- Establish the private documentation website workspace and shared project maintenance skill. Public release and live deployment remain unverified.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesus Graterol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,9 @@
+The fenced-code and optional overview recognition in src/documents/ derives
+from the public jg-agent-hq/src/plans/utilities.ts implementation:
+https://github.com/jesusgraterol/jg-agent-hq
+
+Copyright (c) 2026 Jesus Graterol. MIT License.
+The full license is included in LICENSE.
+
+Only reusable document mechanics are adapted. Consumer approvals, digests,
+authorization, coordination, and project-specific metadata are not included.

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# jg-plans
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A compact planning protocol for people and coding agents. Keep the plan in Markdown, add milestones when they help, and let projects choose their workflows.
+
+Protocol 0.1 is provisional. The [website](https://jg-plans.jesusgraterol.dev) presents the specification, documentation, and examples, with package availability verified independently of the protocol draft.
+
+- [Protocol 0.1](protocol/0.1/README.md)
+- [Examples](examples/README.md)
+- [Getting started](docs/getting-started.md)
+- [Library API](api/README.md) and [CLI](cli/README.md)
+- [Consumer integration](docs/integrations.md)
+- [Development](https://github.com/jesusgraterol/jg-plans/blob/main/docs/development.md)
+- [Website development and visual checks](https://github.com/jesusgraterol/jg-plans/blob/main/website/README.md)
+
+## Project blueprint
+
+| Area                                 | Ownership                                                                                                |
+| ------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| protocol/                            | Normative versioned specification and version index.                                                     |
+| examples/                            | Invented public documents and independently described expected observations.                             |
+| docs/                                | Concise durable concepts and operating guides; API and HTTP/error references stay outside docs/.         |
+| Root package                         | Public reference library and thin CLI.                                                                   |
+| src/                                 | Protocol schemas, tolerant parsers, selected-directory reads, targeted metadata/marker edits, and CLI.   |
+| api/, cli/, errors/                  | Canonical public API, automation, and error references.                                                  |
+| scripts/package/                     | Build, local archive creation, and isolated installed-consumer verification.                             |
+| scripts/release/, .github/workflows/ | Source/checksum receipts, registry/provenance verification, and qualified delivery.                      |
+| website/                             | Private Astro/Tailwind workspace for canonical docs, parsed examples, and verified release presentation. |
+| .agents/skills/jg-plans-maintenance/ | Shared project maintenance skill; Claude discovers the same source through its repository symlink.       |
+
+Users own their documents and can edit or delete them. No history store, metadata field, CLI, or website is required to read Markdown. Optional conformance checks do not authorize execution or become a prerequisite to inspection.
+
+The protocol stays separate from application schemas, approvals, resource allocations, locking and reconciliation. Future jg-skills and HQ adoption are independent integrations.
+
+## Development
+
+Use Node.js 24.15.0 or newer and pnpm 12.14.0.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm format:check
+pnpm check:package
+pnpm check
+```
+
+The [development guide](https://github.com/jesusgraterol/jg-plans/blob/main/docs/development.md) owns checks and package/site boundaries. Root tests build first, exercise public compiled exports, and install the actual tarball in an isolated consumer. Website tests verify production output in both themes and narrow layouts.
+
+The [runnable library example](examples/library.mjs) creates, inspects, updates, and checks documents in an owned temporary directory. Mutations preserve unrelated bytes and require callers to serialize edits to each document; unsupported edits fail without rewriting it. The [API](api/README.md) describes the exact preservation and concurrency limits.
+
+## License
+
+[MIT](LICENSE), copyright Jesus Graterol.

package/api/README.md

@@ -0,0 +1,96 @@
+# Library API
+
+Protocol 0.1 is provisional. These operations describe the implemented reference library. Check the [website's availability label](https://jg-plans.jesusgraterol.dev/docs/api/) before choosing a published package version.
+
+The ESM root exports compiled JavaScript and TypeScript declarations. Node.js 24.15.0 is the runtime floor. Importing jg-plans does not inspect files, log output, or start a process. The only public import path is `jg-plans`.
+
+```ts
+import { PROTOCOL_VERSION, parsePlan, parseMilestones, checkPlan, inspectPlan } from 'jg-plans';
+
+const plan = parsePlan('# Useful legacy Markdown');
+const milestones = parseMilestones('## Milestone 1: Work\n**Status:** pending');
+const check = checkPlan({ plan: plan.source, milestones: milestones.source });
+const observation = await inspectPlan('./jg-plans/example', { maxBytes: 1_048_576 });
+```
+
+## Parsing and checking
+
+`parsePlan(source)` retains the exact source and body. Its `metadata` contains independently validated core fields. `rawMetadata` retains the expanded YAML value, including unknown fields and invalid known values. Missing metadata, malformed YAML, unsupported expansion, and incompatible values receive structured diagnostics; they do not discard the body or authorize work.
+
+YAML uses maxAliasCount: 100 for expansion protection. Recursive aliases, unsafe integer expansions, and values JSON cannot represent receive a `YAML_VALUE_UNAVAILABLE` warning; rawMetadata is unavailable (`null`) and the original YAML remains in source. Raw observations use YAML's JavaScript conversion; source remains authoritative for original numeric spelling and presentation. Independently readable core fields are still observed. An unterminated frontmatter block retains the complete source as body because its boundary is unknown.
+
+`parseMilestones(source)` returns source, recognizable milestones, optional overview rows, overviewPresent, and diagnostics. overviewPresent distinguishes an absent table from an explicitly empty derived table; an existing table that omits observed milestones receives discrepancies. Each entry contains ordinal, title, observed status/ID or null, location, end offset, body, and all recognized status/ID markers. Duplicate markers remain visible and are diagnosed; the first observed marker supplies the convenience status/ID value. Consumers must consider ambiguity diagnostics before acting on it. Fenced examples are ignored. Missing IDs and overview tables are allowed. Gaps are observations, with no reconstructed entries or inferred completion.
+
+`checkPlan({ plan?, milestones? })` checks explicitly supplied strings against preferred writer conformance. Omit absent or deleted documents. It returns `{ conforms, diagnostics }`; error diagnostics make conforms false. It never writes, restores data, or runs as a prerequisite to another operation.
+
+## Selected-directory inspection
+
+`inspectPlan(directory, { maxBytes? }?)` reads only plan.md and milestones.md from that exact directory, concurrently and with a default 1 MiB limit per file. Explicit custom paths and coding-agent-planning/ work as supplied; there is no repository/root/history discovery.
+
+The result includes the resolved directory, each document's path and readable/missing/unreadable state, useful parsed data for readable files, and aggregated diagnostics. A readable empty file differs from a missing file. Orphan milestones remain observable when the plan has been deleted. No predecessor is required or restored.
+
+Bytes must decode strictly as UTF-8. An existing BOM is retained in source. Invalid bytes receive INVALID_ENCODING, and another readable document still contributes observations. File-size failures and nonregular/unreadable targets receive operational diagnostics. Final-component file symlinks are not followed; the selected directory's ancestors are caller-chosen. The library does not silently transcode content.
+
+## Types and schemas
+
+Creation and update contracts are described below. A [runnable library example](../examples/library.mjs) exercises creation, sequential updates, inspection, and checking in an owned temporary directory.
+
+Named public types are IPlanMetadata, IDiagnostic, ISourceLocation, IReadOptions, IPlanDocuments, IParsedPlan, IFrontmatter, IMarker, IMilestone, IOverviewRow, IParsedMilestones, ICheckResult, IDocumentRead, IPlanInspection, ICreatePlanOptions, IPlanCreation, IPlanUpdate, and IPlanUpdateResult.
+
+PlanMetadataSchema defines preferred complete metadata and allows project extensions. DiagnosticSchema, SourceLocationSchema, ReadOptionsSchema, and PlanDocumentsSchema own the corresponding boundary contracts. Known fields are validated independently during tolerant reads. PROTOCOL_VERSION is `0.1`; it is independent of the npm package version.
+
+Source offsets count JavaScript UTF-16 code units. Lines and columns start at one. Marker value spans exclude surrounding whitespace and line endings. Entries and overview rows retain ordinalText; ordinal is null for nonpositive or unsafe integer text, avoiding rounded identities. These are observations, not general-purpose rewrite permission.
+
+## Exclusive creation
+
+```ts
+import { createPlan, updatePlan } from 'jg-plans';
+
+const created = await createPlan({
+  root: './jg-plans', // optional; resolved from the current working directory
+  slug: 'small-change',
+  body: '# Intent\n\nKeep this prose.\n',
+  metadata: { project: { owner: 'example' } },
+  milestones: '## Milestone 1: Implement\n**Status:** pending\n', // optional, verbatim
+});
+await updatePlan(created.directory, { document: 'plan', set: { revision: 2 } });
+```
+
+`createPlan(options)` creates `<unix-seconds>_<slug>/plan.md` exclusively beneath the supplied root, or ./jg-plans. It never discovers or migrates an existing root. Slugs use lowercase ASCII kebab case; the generated directory component must fit 64 characters. The generated relative file paths fit 160 characters. A supplied document ID is opaque and never becomes a path.
+
+The closed CreatePlanOptionsSchema accepts slug, optional root, body, optional JSON metadata, and optional milestones text. Missing core metadata defaults to the generated name as id, one captured ISO creation time for created_at and updated_at, revision 1, and pending status. Supplied values override defaults, including nonconforming known values; diagnostics describe them without refusing to preserve them. Unknown project metadata is retained. The supplied Markdown body and milestone bytes are preserved; creation emits new UTF-8 frontmatter with LF separators.
+
+The result contains directory, parsed plan, parsed milestones or null, and diagnostics. Existing destinations fail without overwriting. Failed creation attempts remove only recognized files created by that call and the empty owned plan directory. Intervening user content is preserved; incomplete cleanup is reported in error.data.cleanupFailedPaths. An empty selected storage root can remain after failure.
+
+## Targeted updates
+
+`updatePlan(directory, patch, { maxBytes? }?)` edits one existing document and returns `{ directory, document, changed, diagnostics }`. The closed PlanUpdateSchema accepts either:
+
+```json
+{ "document": "plan", "set": { "status": "in progress", "revision": 2 } }
+```
+
+```json
+{
+  "document": "milestones",
+  "changes": [{ "select": { "ordinal": 1 }, "set": { "status": "done" } }]
+}
+```
+
+PlanSetSchema allows only id, created_at, updated_at, revision, and status, validated by their preferred core schemas. Supply at least one field. Revision and updated_at change only when explicitly requested. MilestoneSelectorSchema selects one entry by UUID id or positive safe ordinal, never both. MilestoneSetSchema allows status and/or UUID id. Status must be nonblank, trimmed, and contain no CR/LF. Each target occurs at most once per call; combine its changes in one set.
+
+The update reads only the selected document, bounded at 1 MiB by default. A malformed or deleted companion document does not block an independent edit. Missing targets are never recreated. Insertions require an unambiguous location: absent plan fields go before the closing frontmatter delimiter; metadata-free Markdown receives frontmatter containing only requested fields. New status markers go immediately after their heading, and new IDs immediately after an unambiguous canonical status line. Existing misplaced markers are updated in place and remain diagnosed; the overview table and prose are not changed.
+
+Every byte outside the requested value spans or insertion points is preserved, including BOM, supplementary Unicode, unrelated nested metadata, comments, quotes, whitespace, line endings, and final-newline state. Equal values produce a no-op and skip replacement. Existing single quotes are retained when their style can represent the value; replacements otherwise use quoted YAML scalars.
+
+Unsupported edits fail without writing. These include malformed/unterminated frontmatter, a flow-style root mapping, complex/anchored/tagged root keys, merge keys, duplicate affected keys, and affected aliases, anchors, tags, block/multiline scalars, or implicit empty nulls. Duplicate/missing milestone selectors, repeated targets, duplicate affected markers, and overlapping spans also fail. Unrelated nonconforming fields are not a conformance gate. error.data.reason identifies the unsupported case, with field when relevant; it contains no source snippet. This is a conservative scalar/marker editor, with no general YAML or Markdown rewrite API.
+
+Bytes must be valid UTF-8, and replacement strings cannot contain unpaired UTF-16 surrogates. The caller-selected directory and its ancestors are trusted path choices; links below that root are rejected. Replacement preserves file permissions. **Serialize the entire read/edit/write operation for a document, including within one process.** The prior-content comparison detects observed intervening changes, but a comparison-to-rename race remains. No lock, queue, journal, snapshot service, or automatic retry is provided.
+
+CreatePlanOptionsSchema and PlanUpdateSchema are public boundary schemas; PlanSetSchema, MilestoneSelectorSchema, and MilestoneSetSchema expose their constituent contracts. New metadata is JSON-compatible; original YAML source remains authoritative on reads.
+
+## Failures
+
+Invalid operation arguments throw JG_PLANS_INVALID_INPUT: Invalid jg-plans input. File absence, formatting defects, encoding failures, and read failures are returned as inspection diagnostics. Mutations throw operational errors for unsupported text/edits, existing destinations, detected source changes, and read/write failures. See the [error reference](../errors/README.md) for exact codes/messages and per-operation mapping. ERRORS exposes the stable operational codes.
+
+Approval, authorization, stricter profiles, coordination, retention, and execution remain consumer-owned. See the [protocol](../protocol/0.1/README.md) and [integration guide](../docs/integrations.md).

package/cli/README.md

@@ -0,0 +1,85 @@
+# CLI
+
+The executable is tested from the packed archive. Check the [website's availability label](https://jg-plans.jesusgraterol.dev/docs/cli/) for published-package availability, or run the built executable from a checkout.
+
+```sh
+jg-plans inspect --directory ./jg-plans/example
+jg-plans inspect --directory ./custom-root/example --json
+jg-plans inspect --directory ./coding-agent-planning/example --include-body --json
+jg-plans check --directory ./jg-plans/example --json
+jg-plans --help
+jg-plans --version
+```
+
+## Inspect
+
+Inspect reads only the selected plan.md and optional milestones.md. It reports readable, missing, or unreadable files, recognized metadata and progress, and useful partial observations. Unknown metadata and custom status strings remain visible. It does not read history, discover other plans, restore deleted files, or infer permission or completion from absence.
+
+Bodies and complete document sources are excluded by default. `--include-body` explicitly includes them for inspect. Metadata, titles, markers, and locations remain part of ordinary observations.
+
+## Check
+
+Check is an optional assessment against the preferred protocol writer format. Missing required metadata, malformed structures, duplicate markers, and overview discrepancies produce findings. Milestone IDs and overview tables remain optional. A missing milestone file is valid for a plan-only task. A checker result is never an execution approval or a restriction on manual editing.
+
+## Create and update
+
+```sh
+jg-plans create --slug small-change --input create.json --json
+jg-plans create --slug small-change --root ./custom-root --input - --json
+jg-plans update --directory ./jg-plans/example --input update.json --json
+```
+
+Create input is a closed JSON object with body, optional metadata, and optional milestones text:
+
+```json
+{
+  "body": "# Intent\n\nKeep this prose.\n",
+  "metadata": { "project": { "owner": "example" } },
+  "milestones": "## Milestone 1: Implement\n**Status:** pending\n"
+}
+```
+
+Slug and root are command flags, not JSON fields. Creation uses ./jg-plans relative to the working directory by default, without root discovery or migration. It creates an exclusive timestamp_slug directory, defaults missing metadata, preserves supplied body/milestones, and never overwrites. Slugs use lowercase ASCII kebab case; the generated component must fit 64 characters. Returned create data contains directory, plan metadata/rawMetadata, and milestone summaries or null. No body is emitted.
+
+Update input selects one document. For a plan, use `{ "document": "plan", "set": { "status": "done", "revision": 2 } }`. The only allowed fields are id, created_at, updated_at, revision, and status. For milestones:
+
+```json
+{
+  "document": "milestones",
+  "changes": [{ "select": { "ordinal": 1 }, "set": { "status": "done" } }]
+}
+```
+
+Select by ordinal or UUID id, with one change per target. Set status and/or UUID id. The result contains directory, document, and changed. Equal values skip the write. Revision/timestamps never advance implicitly. Overview rows, prose, and extension metadata remain byte-identical. Missing selected files are not recreated. Existing misplaced markers remain in place with diagnostics; new markers require canonical insertion points.
+
+Input comes from a file or `-` for stdin and must be valid UTF-8 JSON, at most 1 MiB by default. `--max-bytes` overrides both mutation-input and selected-document limits. Unknown JSON fields, nonconforming requested core values, invalid encoding, unsupported YAML, ambiguous edits, destination collisions, detected source changes, and I/O failures exit 2. Unsupported edits explain the case in error.data.reason; cleanup failures report owned paths. See [the API](../api/README.md) for precise preservation and unsupported-edit limits.
+
+Serialize commands that edit the same document, including the whole read/edit/write operation. A prior-content check detects observed intervening changes, but the comparison-to-rename race remains. The CLI supplies no lock, queue, retry, or history service.
+
+## Limits and output
+
+`--max-bytes <positive-safe-integer>` overrides the default 1048576-byte per-file bound. Inputs must be valid UTF-8; invalid bytes are diagnosed without replacement/transcoding. Help and version do not read selected plan files.
+
+Human output uses stdout for data and stderr for diagnostics. `--json` emits exactly one JSON envelope on stdout and no human/progress messages:
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "inspect",
+  "data": {},
+  "diagnostics": [],
+  "error": null
+}
+```
+
+Inspect data includes the resolved directory and per-document observations; check also includes conforms. Mutation results are described above. Diagnostics have stable codes, severity, document, message, and an optional source location. Error is null or a safe code/message pair with optional data for a reason, affected core field, or cleanupFailedPaths. Causes are not emitted. Operational inspection failure can retain partial data. Source locations use UTF-16 character offsets and one-based lines/columns. The JSON contract is versioned independently of the protocol.
+
+| Exit | Meaning                                                                                                                       |
+| ---- | ----------------------------------------------------------------------------------------------------------------------------- |
+| 0    | Inspection completed, including absence or document-format/encoding findings; a mutation succeeded; or check found no errors. |
+| 1    | Explicit check found conformance errors.                                                                                      |
+| 2    | Invalid command/arguments or operational failure, including unreadable nonregular files and exceeded byte limits.             |
+
+Unknown/repeated flags, unsupported positionals, empty option values, and unsafe byte limits fail rather than silently changing the command. `--include-body` applies only to inspect.
+
+See the [library API](../api/README.md), [error reference](../errors/README.md), and [protocol](../protocol/0.1/README.md).

package/dist/cli/arguments.d.ts

@@ -0,0 +1,7 @@
+import type { IArguments } from './types.ts';
+/**
+ * Validate a single CLI request before reading documents.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ */
+export declare const parseArguments: (args: string[]) => IArguments;

package/dist/cli/arguments.js

@@ -0,0 +1,66 @@
+import { parseStrictArgs } from 'jg-process';
+import { planErrors } from "../errors/index.js";
+import { ReadOptionsSchema } from "../protocol/index.js";
+/**
+ * Validate a single CLI request before reading documents.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ */
+export const parseArguments = (args) => {
+    const [first, ...tail] = args;
+    const isCommand = Boolean(first && !first.startsWith('-'));
+    let flags;
+    try {
+        flags = parseStrictArgs(isCommand ? tail : args, {
+            directory: { type: 'string' },
+            input: { type: 'string' },
+            slug: { type: 'string' },
+            root: { type: 'string' },
+            'max-bytes': { type: 'string' },
+            'include-body': { type: 'boolean' },
+            json: { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+            version: { type: 'boolean', short: 'v' },
+        });
+    }
+    catch (cause) {
+        // Argument errors may include supplied values; keep the public message stable.
+        throw planErrors.create('invalidInput', { cause });
+    }
+    if (flags.help && flags.version)
+        throw planErrors.create('invalidInput');
+    if (flags.help || args.length === 0)
+        return { command: 'help', json: flags.json, includeBody: false };
+    if (flags.version)
+        return { command: 'version', json: flags.json, includeBody: false };
+    if (first !== 'inspect' && first !== 'check' && first !== 'create' && first !== 'update')
+        throw planErrors.create('invalidInput');
+    if (first === 'create') {
+        if (!flags.slug || !flags.input || flags.directory || flags['include-body'])
+            throw planErrors.create('invalidInput');
+    }
+    else {
+        if (!flags.directory || flags.root || flags.slug)
+            throw planErrors.create('invalidInput');
+        if (first === 'update'
+            ? !flags.input || flags['include-body']
+            : Boolean(flags.input) || (first === 'check' && flags['include-body']))
+            throw planErrors.create('invalidInput');
+    }
+    const maximum = flags['max-bytes'];
+    if (maximum !== undefined && !/^[1-9]\d*$/.test(maximum))
+        throw planErrors.create('invalidInput');
+    const maxBytes = maximum === undefined ? undefined : Number(maximum);
+    if (!ReadOptionsSchema.safeParse({ maxBytes }).success)
+        throw planErrors.create('invalidInput');
+    return {
+        command: first,
+        ...(flags.directory ? { directory: flags.directory } : {}),
+        ...(flags.input ? { input: flags.input } : {}),
+        ...(flags.slug ? { slug: flags.slug } : {}),
+        ...(flags.root ? { root: flags.root } : {}),
+        includeBody: flags['include-body'],
+        json: flags.json,
+        ...(maxBytes === undefined ? {} : { maxBytes }),
+    };
+};

package/dist/cli/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCli } from "./commands.js";
+process.exitCode = await runCli(process.argv.slice(2));

package/dist/cli/commands.d.ts

@@ -0,0 +1,2 @@
+/** CLI entry only: public package imports never load or run this module. */
+export declare const runCli: (args: string[]) => Promise<number>;

package/dist/cli/commands.js

@@ -0,0 +1,201 @@
+import { join } from 'node:path';
+import { getErrorCode, isException } from 'jg-exception';
+import { readBoundedFile } from 'jg-fs';
+import { readStdin } from 'jg-process';
+import { z } from 'zod';
+import { checkPlan } from "../documents/index.js";
+import { decodeSource } from "../edits/index.js";
+import { planErrors } from "../errors/index.js";
+import { createPlan, inspectPlan, updatePlan } from "../files/index.js";
+import { CreatePlanOptionsSchema, DEFAULT_MAX_BYTES, PlanUpdateSchema, } from "../protocol/index.js";
+import { parseArguments } from "./arguments.js";
+const HELP = `jg-plans — inspect Markdown plans without enforcing a workflow
+
+Commands:
+  inspect --directory <path> [--include-body] [--json] [--max-bytes <bytes>]
+  check   --directory <path> [--json] [--max-bytes <bytes>]
+  create  --slug <slug> --input <file-or-dash> [--root <path>] [--json] [--max-bytes <bytes>]
+  update  --directory <path> --input <file-or-dash> [--json] [--max-bytes <bytes>]
+  --help, -h
+  --version, -v
+
+Only the selected plan.md and optional milestones.md are read.
+The default bound is 1048576 bytes per file. Checks are optional.
+Updates to the same document must run sequentially. No history is required.
+Exit 0: completed inspection, successful mutation, or conforming check; 1: conformance errors;
+2: invalid command or operational failure. Missing files do not imply completion.`;
+const projectInspection = (inspection, includeBody) => {
+    const plan = inspection.plan;
+    const milestones = inspection.milestones;
+    const planValue = plan.state === 'readable' ? plan.value : undefined;
+    const milestoneValue = milestones.state === 'readable' ? milestones.value : undefined;
+    return {
+        directory: inspection.directory,
+        plan: {
+            state: plan.state,
+            path: plan.path,
+            ...(planValue
+                ? {
+                    metadata: planValue.metadata,
+                    rawMetadata: planValue.rawMetadata,
+                    frontmatter: planValue.frontmatter,
+                    ...(includeBody ? { source: planValue.source, body: planValue.body } : {}),
+                }
+                : {}),
+        },
+        milestones: {
+            state: milestones.state,
+            path: milestones.path,
+            ...(milestoneValue
+                ? {
+                    overview: milestoneValue.overview,
+                    overviewPresent: milestoneValue.overviewPresent,
+                    milestones: milestoneValue.milestones.map(({ body, ...entry }) => ({
+                        ...entry,
+                        ...(includeBody ? { body } : {}),
+                    })),
+                    ...(includeBody ? { source: milestoneValue.source } : {}),
+                }
+                : {}),
+        },
+    };
+};
+const readMutationInput = async (input, maxBytes) => {
+    let bytes;
+    try {
+        bytes = input === '-' ? await readStdin({ maxBytes }) : await readBoundedFile(input, maxBytes);
+    }
+    catch (cause) {
+        const reason = getErrorCode(cause);
+        throw planErrors.create('readFailed', { cause, ...(reason ? { data: { reason } } : {}) });
+    }
+    let text;
+    try {
+        text = decodeSource(bytes);
+    }
+    catch {
+        throw planErrors.create('unsupportedEncoding');
+    }
+    try {
+        return JSON.parse(text.replace(/^\uFEFF/, ''));
+    }
+    catch {
+        // JSON syntax errors may contain input snippets; keep those unsafe causes out of errors.
+        throw planErrors.create('invalidInput');
+    }
+};
+/** CLI entry only: public package imports never load or run this module. */
+export const runCli = async (args) => {
+    let json = args.includes('--json');
+    let command = args[0] ?? 'help';
+    try {
+        const options = parseArguments(args);
+        json = options.json;
+        command = options.command;
+        let data;
+        let diagnostics = [];
+        let error = null;
+        let exitCode = 0;
+        if (options.command === 'help')
+            data = { help: HELP };
+        else if (options.command === 'version') {
+            const raw = JSON.parse((await readBoundedFile(join(import.meta.dirname, '../../package.json'), 1024 * 1024)).toString('utf8'));
+            const manifest = z.object({ version: z.string() }).safeParse(raw);
+            if (!manifest.success)
+                throw planErrors.create('readFailed');
+            data = { version: manifest.data.version };
+        }
+        else if (options.command === 'create') {
+            const raw = await readMutationInput(options.input, options.maxBytes ?? DEFAULT_MAX_BYTES);
+            const parsed = CreatePlanOptionsSchema.omit({ slug: true, root: true }).safeParse(raw);
+            if (!parsed.success)
+                throw planErrors.create('invalidInput');
+            const result = await createPlan({
+                ...parsed.data,
+                slug: options.slug,
+                ...(options.root ? { root: options.root } : {}),
+            });
+            diagnostics = result.diagnostics;
+            data = {
+                directory: result.directory,
+                plan: { metadata: result.plan.metadata, rawMetadata: result.plan.rawMetadata },
+                milestones: result.milestones?.milestones.map((entry) => ({
+                    ordinal: entry.ordinal,
+                    ordinalText: entry.ordinalText,
+                    title: entry.title,
+                    id: entry.id,
+                    status: entry.status,
+                    location: entry.location,
+                })) ?? null,
+            };
+        }
+        else if (options.command === 'update') {
+            const raw = await readMutationInput(options.input, options.maxBytes ?? DEFAULT_MAX_BYTES);
+            const parsed = PlanUpdateSchema.safeParse(raw);
+            if (!parsed.success)
+                throw planErrors.create('invalidInput');
+            const result = await updatePlan(options.directory, parsed.data, options.maxBytes === undefined ? {} : { maxBytes: options.maxBytes });
+            diagnostics = result.diagnostics;
+            data = { directory: result.directory, document: result.document, changed: result.changed };
+        }
+        else {
+            const inspection = await inspectPlan(options.directory, options.maxBytes === undefined ? {} : { maxBytes: options.maxBytes });
+            diagnostics = inspection.diagnostics;
+            const operationalFailure = diagnostics.some((item) => item.code === 'UNREADABLE_DOCUMENT' || item.code === 'FILE_TOO_LARGE');
+            if (options.command === 'check') {
+                if (inspection.plan.state !== 'unreadable' &&
+                    inspection.milestones.state !== 'unreadable') {
+                    diagnostics = checkPlan({
+                        ...(inspection.plan.state === 'readable' ? { plan: inspection.plan.value.source } : {}),
+                        ...(inspection.milestones.state === 'readable'
+                            ? { milestones: inspection.milestones.value.source }
+                            : {}),
+                    }).diagnostics;
+                }
+                const conforms = !diagnostics.some((item) => item.severity === 'error');
+                data = { ...projectInspection(inspection, false), conforms };
+                exitCode = conforms ? 0 : 1;
+            }
+            else
+                data = projectInspection(inspection, options.includeBody);
+            if (operationalFailure) {
+                const failure = planErrors.create('readFailed');
+                error = { code: failure.code, message: failure.message };
+                exitCode = 2;
+            }
+        }
+        if (json)
+            console.log(JSON.stringify({ schemaVersion: 1, command, data, diagnostics, error }));
+        else {
+            if ('help' in data)
+                console.log(data.help);
+            else if ('version' in data)
+                console.log(data.version);
+            else
+                console.log(JSON.stringify(data, null, 2));
+            for (const item of diagnostics)
+                console.error(`${item.document}${item.location ? `:${item.location.line}:${item.location.column}` : ''} ${item.severity} ${item.code}: ${item.message}`);
+            if (error)
+                console.error(`${error.code}: ${error.message}`);
+        }
+        return exitCode;
+    }
+    catch (cause) {
+        const failure = isException(cause) && planErrors.is(cause)
+            ? cause
+            : planErrors.create('readFailed', { cause });
+        const error = {
+            code: failure.code,
+            message: failure.message,
+            ...(failure.data ? { data: failure.data } : {}),
+        };
+        if (json)
+            console.log(JSON.stringify({ schemaVersion: 1, command, data: null, diagnostics: [], error }));
+        else {
+            console.error(`${error.code}: ${error.message}. Run jg-plans --help.`);
+            if (failure.data)
+                console.error(`Details: ${JSON.stringify(failure.data)}`);
+        }
+        return 2;
+    }
+};

package/dist/cli/types.d.ts

@@ -0,0 +1,11 @@
+/** Validated CLI requests; file paths stay explicit. */
+export type IArguments = {
+    command: 'inspect' | 'check' | 'create' | 'update' | 'help' | 'version';
+    directory?: string;
+    maxBytes?: number;
+    input?: string;
+    slug?: string;
+    root?: string;
+    includeBody: boolean;
+    json: boolean;
+};

package/dist/cli/types.js

@@ -0,0 +1 @@
+export {};

package/dist/documents/check.d.ts

@@ -0,0 +1,10 @@
+import { type IPlanDocuments } from '../protocol/index.ts';
+import type { ICheckResult } from './types.ts';
+/**
+ * Explicitly check preferred writer conformance. Inspection never requires this operation.
+ * @param documents Selected document sources; omit deleted or absent files.
+ * @returns Conformance and diagnostics. No source is changed or restored.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ */
+export declare const checkPlan: (documents: IPlanDocuments) => ICheckResult;

package/dist/documents/check.js

@@ -0,0 +1,26 @@
+import { planErrors } from "../errors/index.js";
+import { PlanDocumentsSchema } from "../protocol/index.js";
+import { parseMilestones } from "./milestones.js";
+import { parsePlan } from "./plan.js";
+import { diagnostic } from "./utilities.js";
+/**
+ * Explicitly check preferred writer conformance. Inspection never requires this operation.
+ * @param documents Selected document sources; omit deleted or absent files.
+ * @returns Conformance and diagnostics. No source is changed or restored.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ */
+export const checkPlan = (documents) => {
+    const parsed = PlanDocumentsSchema.safeParse(documents);
+    if (!parsed.success)
+        throw planErrors.create('invalidInput');
+    const diagnostics = parsed.data.plan === undefined
+        ? [diagnostic('plan', 'MISSING_PLAN', 'The plan file is absent.')]
+        : parsePlan(parsed.data.plan).diagnostics;
+    if (parsed.data.milestones !== undefined) {
+        diagnostics.push(...parseMilestones(parsed.data.milestones).diagnostics);
+        if (parsed.data.plan === undefined)
+            diagnostics.push(diagnostic('milestones', 'ORPHAN_MILESTONES', 'Milestones remain without a plan; no plan is restored.', undefined, 'warning'));
+    }
+    return { conforms: !diagnostics.some((item) => item.severity === 'error'), diagnostics };
+};