light-plan 0.0.0-stage → 0.1.0

package/dist/remote/provider.js

@@ -0,0 +1,27 @@
+/**
+ * The shape every provider adapter conforms to.
+ *
+ * A provider is looked up by name in `registry.ts`. It exposes four members,
+ * plus one optional descriptor:
+ *
+ *   - `config`       a zod schema validating the provider's own slice of a
+ *                    remote declaration — its `connection` and `mapping`
+ *                    blocks. Core validates only the frame; this validates the
+ *                    contents, when the remote is opened (LP-259).
+ *   - `capabilities` what the platform can natively hold (capabilities.ts).
+ *   - `translator`   the two-way vocabulary mapping: a board op becomes a
+ *                    request description, a remote record becomes board fields.
+ *   - `connector`    a factory that turns a validated connection block into a
+ *                    connector the executor (LP-490) can drive.
+ *   - `credentials`  (optional) which connection keys hold secrets and each
+ *                    one's conventional env var, for the resolver (LP-295).
+ *
+ * The op / request / record vocabularies here are the *shape* of the sync; the
+ * push planner (LP-280) emits the ops, the pull planner (LP-281) consumes the
+ * records, and the executor (LP-490) walks the requests through a connector.
+ * Those stories may refine these types — a provider adapter exposes the four
+ * members (plus the optional `credentials` descriptor) and nothing else, so supporting a fourth platform is a folder plus a
+ * line in the registry, never an edit to the planners or to core.
+ */
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/remote/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/remote/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG"}

package/dist/remote/providers/github/config.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The GitHub provider's own slice of a remote declaration.
+ *
+ * Core validates the frame — that a remote has a `provider`, a scope, a
+ * direction and two policies. This schema validates the contents of the
+ * `connection` and `mapping` blocks for GitHub specifically, and is called
+ * when the remote is opened (LP-259), exactly as `storage/views.ts` owns the
+ * contents of a view file.
+ *
+ * GitHub has no native issue types, no custom fields and no workflow beyond
+ * open/closed, so every board vocabulary element rides on labels:
+ *
+ *   - `types`      board type → `{ labels: [...] }`  (the labels that mark it)
+ *   - `statuses`   board status id → the label(s) that carry it, plus which
+ *                  one a push writes and whether the status closes the issue
+ *   - `attributes` board attribute name → the label prefix that carries its
+ *                  value (`story_points: 3` becomes the label `Points:3`)
+ *   - `accounts`   `{ via: <attribute> }` — which resource attribute carries
+ *                  the GitHub login (LP-271)
+ *   - `periods`    which period level maps to the native carrier and which
+ *                  carrier carries it — `{ container: <type>, carrier: milestones | iteration }`,
+ *                  or the shorthand `milestones` / `iteration` (LP-313); the
+ *                  other levels ride the managed block
+ */
+import { z } from 'zod';
+export declare const githubConfigSchema: z.ZodObject<{
+    connection: z.ZodObject<{
+        repo: z.ZodString;
+        token: z.ZodOptional<z.ZodString>;
+        base_url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    mapping: z.ZodObject<{
+        project: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        fields: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        status_precedence: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            issue: "issue";
+            project: "project";
+        }>>>;
+        types: z.ZodPipe<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodObject<{
+            remote: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+            type: z.ZodOptional<z.ZodString>;
+            labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>]>>>, z.ZodTransform<import("../../mapping.js").TypeMappings, Record<string, string | string[] | {
+            remote?: string | string[] | undefined;
+            type?: string | undefined;
+            labels?: string[] | undefined;
+        }>>>;
+        statuses: z.ZodPipe<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>, z.ZodObject<{
+            remote: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+            push: z.ZodOptional<z.ZodString>;
+            closed: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>]>>>, z.ZodTransform<import("../../mapping.js").StatusMappings, Record<string, string | string[] | {
+            remote: string | string[];
+            push?: string | undefined;
+            closed?: boolean | undefined;
+        }>>>;
+        attributes: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        accounts: z.ZodOptional<z.ZodObject<{
+            via: z.ZodString;
+        }, z.core.$strip>>;
+        periods: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            milestones: "milestones";
+            iteration: "iteration";
+        }>, z.ZodObject<{
+            container: z.ZodString;
+            carrier: z.ZodOptional<z.ZodEnum<{
+                milestones: "milestones";
+                iteration: "iteration";
+            }>>;
+        }, z.core.$strip>]>>, z.ZodTransform<{
+            container: string;
+            carrier?: "milestones" | "iteration" | undefined;
+        } | {
+            carrier: "milestones" | "iteration";
+        } | undefined, "milestones" | "iteration" | {
+            container: string;
+            carrier?: "milestones" | "iteration" | undefined;
+        } | undefined>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** The validated shape of a GitHub remote declaration. */
+export type GithubConfig = z.infer<typeof githubConfigSchema>;
+/** The `mapping` block, after validation (every sub-map present, statuses normalized). */
+export type GithubMapping = GithubConfig['mapping'];

package/dist/remote/providers/github/config.js

@@ -0,0 +1,161 @@
+/**
+ * The GitHub provider's own slice of a remote declaration.
+ *
+ * Core validates the frame — that a remote has a `provider`, a scope, a
+ * direction and two policies. This schema validates the contents of the
+ * `connection` and `mapping` blocks for GitHub specifically, and is called
+ * when the remote is opened (LP-259), exactly as `storage/views.ts` owns the
+ * contents of a view file.
+ *
+ * GitHub has no native issue types, no custom fields and no workflow beyond
+ * open/closed, so every board vocabulary element rides on labels:
+ *
+ *   - `types`      board type → `{ labels: [...] }`  (the labels that mark it)
+ *   - `statuses`   board status id → the label(s) that carry it, plus which
+ *                  one a push writes and whether the status closes the issue
+ *   - `attributes` board attribute name → the label prefix that carries its
+ *                  value (`story_points: 3` becomes the label `Points:3`)
+ *   - `accounts`   `{ via: <attribute> }` — which resource attribute carries
+ *                  the GitHub login (LP-271)
+ *   - `periods`    which period level maps to the native carrier and which
+ *                  carrier carries it — `{ container: <type>, carrier: milestones | iteration }`,
+ *                  or the shorthand `milestones` / `iteration` (LP-313); the
+ *                  other levels ride the managed block
+ */
+import { z } from 'zod';
+import { normalizeStatusMappings, normalizeTypeMappings } from '../../mapping.js';
+/**
+ * GitHub repo coordinates as `owner/repo`. Loose on purpose — the only thing
+ * that matters is that a repo is named, because there is no sensible default.
+ */
+const repoPattern = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+/**
+ * One `mapping.types` value: the remote name this board type becomes, as a
+ * bare string (`user_story: Story`) or the object form
+ * (`user_story: { remote: Story }`). One name, not a list — a board type and
+ * a remote type are one-to-one, unlike a status, where several remote states
+ * can mean one board status.
+ *
+ * The superseded spellings (`type`, `labels`, and a list) are still accepted
+ * and folded to the single name by `normalizeTypeMappings`, so a board written
+ * against an older shape keeps working.
+ */
+const typeEntrySchema = z.union([
+    z.string().min(1),
+    z.array(z.string().min(1)).min(1),
+    z.object({
+        remote: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]).optional(),
+        type: z.string().min(1).optional(),
+        labels: z.array(z.string().min(1)).min(1).optional(),
+    }),
+]);
+/**
+ * One `mapping.statuses` value: a single remote state (`done: Done`), a list
+ * (`done: [Done, "Won't Fix", Duplicate]`), or the full object form
+ * (`done: { remote: [Done], push: Done, closed: true }`). The shape is
+ * validated here; `normalizeStatusMappings` (in `mapping.ts`) expands every
+ * spelling to the object form the engine reads.
+ */
+const statusEntrySchema = z.union([
+    z.string().min(1),
+    z.array(z.string().min(1)).min(1),
+    z.object({
+        remote: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]),
+        push: z.string().min(1).optional(),
+        closed: z.boolean().optional(),
+    }),
+]);
+export const githubConfigSchema = z.object({
+    connection: z.object({
+        /** `owner/repo` the remote issues live in. */
+        repo: z
+            .string({ error: 'connection.repo is required' })
+            .min(1, 'connection.repo is required')
+            .regex(repoPattern, 'must be "owner/repo"'),
+        /**
+         * API token, written as `${GITHUB_TOKEN}` or omitted. Omit and the
+         * resolver (LP-295) looks it up in `.lpm/credentials.json`, then
+         * `GITHUB_TOKEN`; the connector itself treats a missing token as an
+         * unauthenticated request.
+         */
+        token: z.string().optional(),
+        /** API root, e.g. a GitHub Enterprise host. Defaults to api.github.com. */
+        base_url: z.string().optional(),
+    }),
+    mapping: z.object({
+        /**
+         * The Projects v2 Project this board's fields live in (LP-310), named
+         * either by its number (`project: 7`) or by its title — never by its
+         * `PVT_...` node id, which is what the resolver caches so nobody has to
+         * read or write one. Absent means no Project is declared and Projects v2
+         * is not used.
+         */
+        project: z
+            .union([z.number().int().positive(), z.string().min(1)])
+            .optional(),
+        /**
+         * Board field → Projects v2 field name (LP-310). Keys are board field
+         * names — canonical fields (`status`, `title`) and declared attribute
+         * names (`priority`, `story_points`) — and values are the Project field
+         * names they live in, written in plain words so the config stays
+         * readable. The resolver caches each value's node id (and, for a single
+         * select, its option ids) so the sync addresses fields by id.
+         */
+        fields: z.record(z.string(), z.string().min(1)).default({}),
+        /**
+         * Which of GitHub's two "is it done" signals wins when they disagree
+         * (LP-312). GitHub has two independent sources of truth for a board
+         * status: the issue's own `state` (`open`/`closed`), and the Project
+         * single-select column `fields.status` points at. They usually agree, but
+         * a human can close an issue without moving the column (or move the column
+         * without closing the issue). When they disagree on terminality:
+         *
+         *   - `issue`   (default) the issue state wins — a closed issue pulls
+         *               back as the terminal status even when the column was not
+         *               moved;
+         *   - `project` the column wins — a column moved to a non-terminal value
+         *               overrides a closed issue.
+         *
+         * Whichever side loses is reported as a discrepancy, never silently
+         * dropped.
+         */
+        status_precedence: z.enum(['issue', 'project']).optional().default('issue'),
+        types: z
+            .record(z.string(), typeEntrySchema)
+            .default({})
+            .transform((entries) => normalizeTypeMappings(entries)),
+        statuses: z
+            .record(z.string(), statusEntrySchema)
+            .default({})
+            .transform((entries) => normalizeStatusMappings(entries)),
+        attributes: z.record(z.string(), z.string()).default({}),
+        accounts: z
+            .object({
+            /** Resource attribute whose value is the GitHub login. */
+            via: z.string().min(1),
+        })
+            .optional(),
+        periods: z
+            .union([
+            /** The shorthand: `periods: milestones` or `periods: iteration`. */
+            z.enum(['milestones', 'iteration']),
+            z.object({
+                /** The period type that maps to the native carrier (`sprint`). */
+                container: z.string().min(1),
+                /**
+                 * The carrier: `milestones` (default) writes a repository milestone,
+                 * `iteration` writes a Project iteration field (LP-313). The
+                 * iteration field's name is `mapping.fields.period`.
+                 */
+                carrier: z.enum(['milestones', 'iteration']).optional(),
+            }),
+        ])
+            .optional()
+            .transform((value) => {
+            if (typeof value === 'string')
+                return { carrier: value };
+            return value;
+        }),
+    }),
+});
+//# sourceMappingURL=config.js.map

package/dist/remote/providers/github/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../src/remote/providers/github/config.ts"],"names":[],"mappings":"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"}

package/dist/remote/providers/github/connector.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The GitHub connector — a live connection to one repo, driven by the executor
+ * (LP-490).
+ *
+ * Built from a validated `connection` block (`repo`, optional `token` and
+ * `base_url`). All network I/O in the remote layer lives here, never in the
+ * planners: `planPush` and `planPull` stay pure, and a dry-run shares their
+ * code path because the executor is the only thing that ever calls this.
+ *
+ * GitHub cannot hard-delete an issue over the REST API, so `delete` closes the
+ * issue instead — the degradation is documented here rather than silently
+ * pretended away, and the capabilities of the provider say as much.
+ *
+ * `request.period` is applied to the configured carrier (LP-313): a
+ * `milestones` carrier resolves the period's name to a repository milestone
+ * (creating it when absent) and writes `milestone` on the issue; an
+ * `iteration` carrier resolves the period's name to a Project iteration and
+ * writes the Project field value. A `null` period clears the carrier.
+ *
+ * `request.parent` is applied as a native sub-issue where the account has the
+ * API (LP-309): the issue is filed, then added to its parent through the
+ * sub-issues endpoint. The executor only sets `parent` when the resolved
+ * hierarchy encoding is `sub-issues` and the document sits within the native
+ * depth; deeper parents ride the managed block instead (see `hierarchy.ts`).
+ */
+import type { Connector, ConnectorContext } from '../../provider.js';
+/**
+ * Build a GitHub connector from a validated connection block.
+ *
+ * `repo` is required (the schema enforces it); `token` authenticates when
+ * present, and `base_url` points at a GitHub Enterprise host when set.
+ */
+export declare function githubConnector(connection: Record<string, unknown>, _mapping?: Record<string, unknown>, context?: ConnectorContext): Connector;