light-plan 0.0.0-stage → 0.1.0

package/dist/remote/providers/github/project-provision.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Projects v2 field and option provisioning (LP-311): what `lpm remote
+ * provision` creates beyond the labels LP-308 already handles.
+ *
+ * A mapping that names a Project field which does not exist is the single most
+ * common setup failure, and creating it is one GraphQL mutation — so this
+ * module computes the fields the mapping needs, compares them against the
+ * Project's *current* state (as resolved and cached by LP-310), and produces a
+ * plan of mutations. It is idempotent by construction: the plan is always
+ * "desired minus current", so a second run against an unchanged Project is
+ * empty.
+ *
+ * ## Field types, from board vocabulary
+ *
+ *   - the status column, and any `enum` attribute → `SINGLE_SELECT`, with its
+ *     options in board order (the status field reads left-to-right the way the
+ *     config writes it);
+ *   - the effort attribute (and any other `int` / `float` attribute) → `NUMBER`;
+ *   - a `date` attribute → `DATE`;
+ *   - everything else → `TEXT`.
+ *
+ * ## Adding options re-sends the whole list
+ *
+ * GitHub has no "add one option" mutation. `updateProjectV2Field` *replaces*
+ * the option list, so adding a missing option means sending the existing
+ * options back — each carrying its `id`, which is what preserves the option's
+ * identity and stops existing item values from being cleared — followed by the
+ * missing ones in desired order. The existing options are untouched: same
+ * names, same ids.
+ *
+ * ## Pure vs I/O
+ *
+ * `desiredProjectFields` and `planProjectProvision` are pure (no disk, no
+ * network); `provisionProjectGraphql` is the network half, driven through the
+ * same `graphql` connector entry point LP-310 added, so a dry-run prints the
+ * plan and never reaches this function.
+ */
+import type { LoadedBoard } from '../../../core/board/load.js';
+import type { AttributeDefs } from '../../provider.js';
+import type { OpenedRemote } from '../../remotes.js';
+import type { ProjectGraphqlConnector, ProjectIds } from './projects.js';
+/** The `ProjectV2CustomFieldType` values a mapping can produce. */
+export type ProjectDataType = 'TEXT' | 'NUMBER' | 'DATE' | 'SINGLE_SELECT' | 'ITERATION';
+/** One field the mapping needs, in Project vocabulary. */
+export interface DesiredProjectField {
+    /** The Project field name, as written in `mapping.fields`. */
+    name: string;
+    /** What kind of field to create. */
+    dataType: ProjectDataType;
+    /** Ordered option names — only for `SINGLE_SELECT`, empty otherwise. */
+    options: string[];
+}
+/** One field to create — its name does not exist in the Project today. */
+export interface CreateProjectFieldPlan {
+    name: string;
+    dataType: ProjectDataType;
+    options: string[];
+}
+/** Options to add to one existing single-select field. */
+export interface AddProjectOptionsPlan {
+    fieldName: string;
+    fieldId: string;
+    /**
+     * The full option list to send — `updateProjectV2Field` replaces the list,
+     * so the existing options are sent back (each with its id, to preserve its
+     * identity) followed by the missing ones in desired order.
+     */
+    options: Array<{
+        name: string;
+        id?: string;
+    }>;
+    /** Just the missing option names, for the report. */
+    missing: string[];
+}
+/** What a push would (or did) create before filing: fields and options. */
+export interface ProjectProvisionPlan {
+    createFields: CreateProjectFieldPlan[];
+    addOptions: AddProjectOptionsPlan[];
+    /** True when nothing needs creating — the second-run, nothing-to-do case. */
+    empty: boolean;
+}
+/** What one `provisionProjectGraphql` run actually created. */
+export interface ProjectProvisionOutcome {
+    /** Project field names created. */
+    created: string[];
+    /** Options added per field, each with the names that were missing. */
+    optionsAdded: Array<{
+        field: string;
+        added: string[];
+    }>;
+}
+/**
+ * The Project field type a board field needs. `status` is a single select (the
+ * board's columns); `title` is text; `period` is an iteration field when the
+ * carrier is an iteration (LP-313); a declared attribute maps by its type —
+ * enum to a single select, int/float to a number, date to a date — and
+ * anything else (an unknown key, a string/bool/array attribute) is text.
+ */
+export declare function projectDataTypeOf(boardField: string, defs: AttributeDefs): ProjectDataType;
+/**
+ * The fields the mapping names, each with its Project type and — for a single
+ * select — its ordered options.
+ *
+ * `status` options are the remote status labels in board order (`mapping.
+ * statuses` is the source of the label, so a renamed remote status is used,
+ * not the board's own label); an enum attribute's options are its declared
+ * `values`, in declaration order. Deduplicated by Project field name (two
+ * board fields mapping to one Project field is a config mistake; the first
+ * spelling wins rather than provisioning twice).
+ */
+export declare function desiredProjectFields(board: LoadedBoard, remote: OpenedRemote): DesiredProjectField[];
+/**
+ * Compare the mapping's desired fields against the Project's current state and
+ * return what is missing. A field whose name is absent is created; a
+ * single-select field that exists but lacks options gains exactly the missing
+ * ones (existing options are re-sent, never dropped or renamed). Idempotent:
+ * an unchanged Project yields an empty plan.
+ */
+export declare function planProjectProvision(current: ProjectIds, desired: DesiredProjectField[]): ProjectProvisionPlan;
+/**
+ * Execute a provisioning plan against the live Project, one mutation at a
+ * time: create each missing field (with its options), then add the missing
+ * options to each existing single-select. Returns what was created; a failed
+ * mutation throws a `BoardError` naming the operation and — for a permission
+ * failure — the required scope.
+ *
+ * The caller re-resolves and re-caches the ids afterwards (LP-310), so the
+ * new field and option node ids land in `.lpm/remotes/<name>/github.json`.
+ */
+export declare function provisionProjectGraphql(connector: ProjectGraphqlConnector, projectId: string, plan: ProjectProvisionPlan): Promise<ProjectProvisionOutcome>;

package/dist/remote/providers/github/project-provision.js

@@ -0,0 +1,247 @@
+/**
+ * Projects v2 field and option provisioning (LP-311): what `lpm remote
+ * provision` creates beyond the labels LP-308 already handles.
+ *
+ * A mapping that names a Project field which does not exist is the single most
+ * common setup failure, and creating it is one GraphQL mutation — so this
+ * module computes the fields the mapping needs, compares them against the
+ * Project's *current* state (as resolved and cached by LP-310), and produces a
+ * plan of mutations. It is idempotent by construction: the plan is always
+ * "desired minus current", so a second run against an unchanged Project is
+ * empty.
+ *
+ * ## Field types, from board vocabulary
+ *
+ *   - the status column, and any `enum` attribute → `SINGLE_SELECT`, with its
+ *     options in board order (the status field reads left-to-right the way the
+ *     config writes it);
+ *   - the effort attribute (and any other `int` / `float` attribute) → `NUMBER`;
+ *   - a `date` attribute → `DATE`;
+ *   - everything else → `TEXT`.
+ *
+ * ## Adding options re-sends the whole list
+ *
+ * GitHub has no "add one option" mutation. `updateProjectV2Field` *replaces*
+ * the option list, so adding a missing option means sending the existing
+ * options back — each carrying its `id`, which is what preserves the option's
+ * identity and stops existing item values from being cleared — followed by the
+ * missing ones in desired order. The existing options are untouched: same
+ * names, same ids.
+ *
+ * ## Pure vs I/O
+ *
+ * `desiredProjectFields` and `planProjectProvision` are pure (no disk, no
+ * network); `provisionProjectGraphql` is the network half, driven through the
+ * same `graphql` connector entry point LP-310 added, so a dry-run prints the
+ * plan and never reaches this function.
+ */
+import { BoardError } from '../../../core/errors.js';
+import { mapStatusToRemote, normalizeStatusMappings } from '../../mapping.js';
+import { attributeDefsOf } from '../../preflight.js';
+// ---------------------------------------------------------------------------
+// Field types, from board vocabulary
+// ---------------------------------------------------------------------------
+/** A loose record read off a mapping block. */
+function asRecord(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value;
+    }
+    return {};
+}
+/**
+ * The Project field type a board field needs. `status` is a single select (the
+ * board's columns); `title` is text; `period` is an iteration field when the
+ * carrier is an iteration (LP-313); a declared attribute maps by its type —
+ * enum to a single select, int/float to a number, date to a date — and
+ * anything else (an unknown key, a string/bool/array attribute) is text.
+ */
+export function projectDataTypeOf(boardField, defs) {
+    if (boardField === 'status')
+        return 'SINGLE_SELECT';
+    if (boardField === 'title')
+        return 'TEXT';
+    if (boardField === 'period')
+        return 'ITERATION';
+    switch (defs[boardField]?.type) {
+        case 'enum':
+            return 'SINGLE_SELECT';
+        case 'int':
+        case 'float':
+            return 'NUMBER';
+        case 'date':
+            return 'DATE';
+        default:
+            return 'TEXT';
+    }
+}
+/**
+ * The fields the mapping names, each with its Project type and — for a single
+ * select — its ordered options.
+ *
+ * `status` options are the remote status labels in board order (`mapping.
+ * statuses` is the source of the label, so a renamed remote status is used,
+ * not the board's own label); an enum attribute's options are its declared
+ * `values`, in declaration order. Deduplicated by Project field name (two
+ * board fields mapping to one Project field is a config mistake; the first
+ * spelling wins rather than provisioning twice).
+ */
+export function desiredProjectFields(board, remote) {
+    const fields = asRecord(remote.mapping['fields']);
+    const defs = attributeDefsOf(board);
+    const statusMappings = normalizeStatusMappings(asRecord(remote.mapping['statuses']));
+    const statusOptions = board.config.statuses
+        .map((status) => mapStatusToRemote(statusMappings, status.id))
+        .filter((label) => typeof label === 'string');
+    const byName = new Map();
+    for (const [boardField, rawName] of Object.entries(fields)) {
+        const name = String(rawName);
+        if (name === '' || byName.has(name))
+            continue;
+        const dataType = projectDataTypeOf(boardField, defs);
+        let options = [];
+        if (boardField === 'status') {
+            options = statusOptions;
+        }
+        else {
+            const def = defs[boardField];
+            if (def?.type === 'enum')
+                options = [...(def.values ?? [])];
+        }
+        // GitHub requires at least one option for a single-select field; a
+        // single-select with nothing to select cannot be created, so it is skipped
+        // rather than sent as a doomed mutation.
+        if (dataType === 'SINGLE_SELECT' && options.length === 0)
+            continue;
+        byName.set(name, { name, dataType, options });
+    }
+    return [...byName.values()];
+}
+// ---------------------------------------------------------------------------
+// The plan: desired minus current
+// ---------------------------------------------------------------------------
+/**
+ * Compare the mapping's desired fields against the Project's current state and
+ * return what is missing. A field whose name is absent is created; a
+ * single-select field that exists but lacks options gains exactly the missing
+ * ones (existing options are re-sent, never dropped or renamed). Idempotent:
+ * an unchanged Project yields an empty plan.
+ */
+export function planProjectProvision(current, desired) {
+    const createFields = [];
+    const addOptions = [];
+    for (const field of [...desired].sort((a, b) => a.name.localeCompare(b.name))) {
+        const existing = current.fields[field.name];
+        if (existing === undefined) {
+            createFields.push({ name: field.name, dataType: field.dataType, options: field.options });
+            continue;
+        }
+        // The field exists; only a single-select can gain options, and only when
+        // the desired type and the live type both say so — a wrong-typed field is
+        // reported by the id cache's mismatch detection, not re-created.
+        if (field.dataType !== 'SINGLE_SELECT' || existing.type !== 'SINGLE_SELECT') {
+            continue;
+        }
+        const missing = field.options.filter((name) => existing.options[name] === undefined);
+        if (missing.length === 0)
+            continue;
+        const options = [
+            ...Object.keys(existing.options).map((name) => ({ name, id: existing.options[name] })),
+            ...missing.map((name) => ({ name })),
+        ];
+        addOptions.push({ fieldName: field.name, fieldId: existing.id, options, missing });
+    }
+    return { createFields, addOptions, empty: createFields.length === 0 && addOptions.length === 0 };
+}
+// ---------------------------------------------------------------------------
+// The network half
+// ---------------------------------------------------------------------------
+/** Create a field (with its options, for a single-select). */
+const CREATE_FIELD_MUTATION = `
+mutation($input: CreateProjectV2FieldInput!) {
+  createProjectV2Field(input: $input) {
+    projectV2Field { id }
+  }
+}
+`;
+/** Replace a single-select's options — the only way to add one (LP-311). */
+const UPDATE_FIELD_MUTATION = `
+mutation($input: UpdateProjectV2FieldInput!) {
+  updateProjectV2Field(input: $input) {
+    projectV2Field { id }
+  }
+}
+`;
+/** The `graphql` entry point, or a `BoardError` when the connector has none. */
+function graphqlOf(connector) {
+    if (typeof connector.graphql !== 'function') {
+        throw new BoardError(`The ${connector.name} connector has no GraphQL API`, [
+            'Projects v2 fields are GraphQL-only, so this provider must expose a GraphQL entry point to provision them.',
+        ]);
+    }
+    return connector.graphql.bind(connector);
+}
+/**
+ * The scope a Project-write needs, in both token vocabularies. Named in the
+ * error so an operator knows exactly what to grant, rather than guessing at a
+ * bare 403.
+ */
+const PROJECT_SCOPE = 'write:project (a fine-grained token) or project (a classic token)';
+/**
+ * Turn a GraphQL `errors` payload into a `BoardError`. A permission-shaped
+ * failure (FORBIDDEN / INSUFFICIENT_SCOPES / "not accessible" and friends)
+ * names the required scope; anything else reports the raw message.
+ *
+ * `operation` is the human-readable thing that failed, e.g.
+ * `create Project field "Priority"` — it is the "what could not be created".
+ */
+function mutationError(operation, errors) {
+    const first = errors[0];
+    const message = typeof first?.message === 'string' ? first.message : JSON.stringify(errors[0]);
+    const type = typeof first?.type === 'string' ? first.type : '';
+    const denied = /permission|not accessible|forbidden|insufficient|scope|authoriz/i.test(`${type} ${message}`);
+    if (denied) {
+        return new BoardError(`Cannot ${operation}: the credential lacks the scope to write Project structure`, [`GitHub said: ${message}`, `Required scope: ${PROJECT_SCOPE}`]);
+    }
+    return new BoardError(`Cannot ${operation}`, [`GitHub GraphQL said: ${message}`]);
+}
+/** Send one mutation, throwing a `BoardError` on a GraphQL error. */
+async function mutate(graphql, query, variables, operation) {
+    const body = await graphql(query, variables);
+    const errors = body && typeof body === 'object' ? body['errors'] : undefined;
+    if (Array.isArray(errors) && errors.length > 0) {
+        throw mutationError(operation, errors);
+    }
+}
+/**
+ * Execute a provisioning plan against the live Project, one mutation at a
+ * time: create each missing field (with its options), then add the missing
+ * options to each existing single-select. Returns what was created; a failed
+ * mutation throws a `BoardError` naming the operation and — for a permission
+ * failure — the required scope.
+ *
+ * The caller re-resolves and re-caches the ids afterwards (LP-310), so the
+ * new field and option node ids land in `.lpm/remotes/<name>/github.json`.
+ */
+export async function provisionProjectGraphql(connector, projectId, plan) {
+    const graphql = graphqlOf(connector);
+    const created = [];
+    const optionsAdded = [];
+    for (const field of plan.createFields) {
+        const input = {
+            projectId,
+            dataType: field.dataType,
+            name: field.name,
+        };
+        if (field.dataType === 'SINGLE_SELECT') {
+            input['singleSelectOptions'] = field.options.map((name) => ({ name }));
+        }
+        await mutate(graphql, CREATE_FIELD_MUTATION, { input }, `create Project field "${field.name}"`);
+        created.push(field.name);
+    }
+    for (const entry of plan.addOptions) {
+        await mutate(graphql, UPDATE_FIELD_MUTATION, { input: { fieldId: entry.fieldId, singleSelectOptions: entry.options } }, `add ${entry.missing.length === 1 ? 'an option to' : `${entry.missing.length} options to`} Project field "${entry.fieldName}"`);
+        optionsAdded.push({ field: entry.fieldName, added: entry.missing });
+    }
+    return { created, optionsAdded };
+}
+//# sourceMappingURL=project-provision.js.map

package/dist/remote/providers/github/project-provision.js.map

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

package/dist/remote/providers/github/project-status.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Projects v2 status-field read/write (LP-312).
+ *
+ * Where the board's `status` becomes a Project single-select column, and back
+ * again. LP-310 resolves and caches the project/field/option node ids; LP-311
+ * provisions the field and its options; this module uses both to move a board
+ * status across the wire as a Project column.
+ *
+ * GitHub has **two** independent sources of truth for "is this done": the
+ * issue's own `state` (`open`/`closed`) and the Project single-select column.
+ * They are not one fact stored twice — a human can close an issue without
+ * moving the column, or drag the column without closing the issue. So this
+ * module treats them as two observations and reconciles them by a configured
+ * precedence (`mapping.status_precedence`), reporting the disagreement rather
+ * than silently choosing.
+ *
+ * ## Push vs pull
+ *
+ * Push: a status label (the same remote status label the translator writes as
+ * a label, LP-269) becomes a Project column value. The issue is added to the
+ * Project first when it is not already an item — `addProjectV2ItemById` —
+ * because a field value cannot be set on an item that does not exist.
+ *
+ * Pull: the column's option name and the issue's state are resolved back to a
+ * board status. A `closed` issue is the terminal status whatever the column
+ * says (default `issue` precedence); a column moved to a non-terminal value
+ * while the issue is closed is reported as a discrepancy.
+ *
+ * ## Pure vs I/O
+ *
+ * `planProjectStatusWrite` and `resolveProjectStatus` are pure (no disk, no
+ * network); the GraphQL documents below them are the network half, driven
+ * through the same `connector.graphql` entry point LP-310 added, so a dry-run
+ * prints the plan and never reaches them.
+ */
+import type { StatusDiscrepancy } from '../../provider.js';
+import type { ProjectGraphqlConnector, ProjectIds } from './projects.js';
+/** Which of GitHub's two "done" signals wins when they disagree. */
+export type StatusPrecedence = 'issue' | 'project';
+/** What the two GitHub signals observed for one issue. */
+export interface ProjectStatusObservation {
+    /** The Project single-select's option name, when the item has one. */
+    column?: string;
+    /** The issue's state — `open` or `closed` — when the record carries it. */
+    state?: string;
+}
+/** The resolved board status, plus the disagreement when one was overridden. */
+export interface ProjectStatusResolution {
+    /** The resolved board status id, when either signal resolved one. */
+    status?: string;
+    /** A disagreement between the two signals, when one overrode the other. */
+    discrepancy?: StatusDiscrepancy;
+}
+/** What a push needs to write the status column for one issue. */
+export interface ProjectStatusWrite {
+    /** The Project field name (`mapping.fields.status`). */
+    field: string;
+    /** The remote status label to write — the column's option name. */
+    value: string;
+    /** The option id resolved for the value, when the Project field has it. */
+    optionId?: string;
+    /** True when the field has no option by that name (provision first). */
+    missingOption: boolean;
+}
+/** The Project field name carrying the board's status, or `undefined` when the
+ * mapping does not put status in a Project field. */
+export declare function projectStatusFieldOf(mapping: Record<string, unknown>): string | undefined;
+/** The configured precedence, defaulting to `issue`. */
+export declare function statusPrecedenceOf(mapping: Record<string, unknown>): StatusPrecedence;
+/** The board status whose mapping says `closed: true`, or `undefined`. */
+export declare function terminalStatusOf(mapping: Record<string, unknown>): string | undefined;
+/**
+ * The Project status write a push needs for one status label: the field name,
+ * the value, and the option id resolved from the cached ids. A value with no
+ * matching option is a `missingOption` — reported, never written — because a
+ * write against a non-existent option would be a silent no-op or an error, and
+ * the remedy is the push itself, which creates the field first (LP-311).
+ */
+export declare function planProjectStatusWrite(ids: ProjectIds, fieldName: string, value: string): ProjectStatusWrite;
+/**
+ * Resolve the two GitHub signals — the Project column and the issue state —
+ * back to one board status.
+ *
+ * The column names the specific status (its option names are the remote status
+ * labels LP-311 provisioned, resolved through the status mapping). The issue
+ * state only names terminality: `closed` is the terminal status, `open` is
+ * "not terminal" but names no specific status. So:
+ *
+ *   - `closed` with no usable column → terminal status (the issue was closed
+ *     on GitHub and the column was never moved);
+ *   - a column with an `open` or unknown state → the column's status;
+ *   - the two disagreeing about terminality → the configured precedence
+ *     decides, and the disagreement is reported.
+ *
+ * A column and state that agree (both terminal, or both non-terminal) resolve
+ * with no discrepancy.
+ */
+export declare function resolveProjectStatus(mapping: Record<string, unknown>, observation: ProjectStatusObservation, precedence?: StatusPrecedence): ProjectStatusResolution;
+/** The Project item id for an issue already in the project, or `null`. */
+export declare function findProjectItemId(connector: ProjectGraphqlConnector, projectId: string, issueNodeId: string): Promise<string | null>;
+/** Add an issue to a Project, returning the new item's id. */
+export declare function addProjectItem(connector: ProjectGraphqlConnector, projectId: string, issueNodeId: string): Promise<string>;
+/** Set one single-select field value on an item. */
+export declare function setProjectItemFieldValue(connector: ProjectGraphqlConnector, projectId: string, itemId: string, fieldId: string, optionId: string): Promise<void>;
+/** Read one single-select field's option name off an item, or `undefined`. */
+export declare function readProjectItemFieldValue(connector: ProjectGraphqlConnector, itemId: string, fieldId: string): Promise<string | undefined>;
+/**
+ * Set the status column for one issue: resolve the option id, add the issue to
+ * the Project when it is not already an item, then write the field value.
+ *
+ * A missing option (a status label the Project does not have) is a `BoardError`
+ * naming the remedy — the write is refused rather than silently dropped, which
+ * is exactly the setup failure the push's prerequisite step (LP-311) fixes.
+ */
+export declare function setProjectStatusField(connector: ProjectGraphqlConnector, ids: ProjectIds, fieldName: string, issueNodeId: string, value: string): Promise<void>;