light-plan 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,200 @@
+/**
+ * The Jira 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 Jira Cloud specifically, and is called
+ * when the remote is opened (LP-259), exactly as `storage/views.ts` owns the
+ * contents of a view file.
+ *
+ * Jira Cloud has *native* issue types, workflow statuses (transition-mediated)
+ * and custom fields, so the mapping names them rather than encoding them onto
+ * labels:
+ *
+ *   - `types`      board type → the Jira issuetype name (`{ type: Story }`)
+ *   - `statuses`   board status id → the Jira status name(s) a push targets,
+ *                  plus whether the status is terminal (`closed`) — the flag
+ *                  that lets the sync tell a finished column from an open one
+ *   - `attributes` board attribute name → the Jira custom field id that
+ *                  carries it (`customfield_10016`). Resolving a *name* to an
+ *                  id is LP-324's discovery, not this schema's: the mapping
+ *                  names the id the instance actually has.
+ *   - `accounts`   `{ via: <attribute> }` — which resource attribute carries
+ *                  the Jira account (LP-271, LP-329). `via: email` resolves
+ *                  through Jira's user search and is refused with the
+ *                  `jira_account_id` alternative on a privacy-restricted
+ *                  instance; `via: jira_account_id` (or any other attribute)
+ *                  holds the account id and is used directly, no search.
+ *   - `periods`    `{ container: <period type> }` — which period level maps to
+ *                  a Jira sprint (LP-328); the other levels ride labels
+ *   - `transitions` `{ multi_hop: <bool> }` — whether a status change may walk
+ *                  the workflow several transitions (LP-326); off by default
+ *   - `transition_fields` field key → value, the answers for transition
+ *                  screens whose fields are required (a resolution, a reason)
+ *
+ * The connection block carries the Cloud site, the project key and the agile
+ * board id (enables sprint mapping), plus the identity resolved through the
+ * credential chain — `email` and `token` name *where* the secret comes from,
+ * never the secret itself (LP-290).
+ */
+import { z } from 'zod';
+import { normalizeStatusMappings, normalizeTypeMappings } from '../../mapping.js';
+/**
+ * The Cloud site URL. Accepts `https://<org>.atlassian.net` and a Cloud site
+ * on a custom domain (`https://jira.acme.com`) — the two shapes Cloud serves.
+ * A Server/Data Center URL is indistinguishable from a custom domain by URL
+ * alone, so it is not refused here; the connector reports it with a clear
+ * "not supported" when the Cloud API turns out not to be there.
+ */
+const siteSchema = z
+    .string({ error: 'connection.site is required' })
+    .min(1, 'connection.site is required')
+    .refine((value) => /^https:\/\/[^/\s]+/.test(value.trim()), {
+    message: 'must be an https URL, e.g. https://acme.atlassian.net',
+})
+    .refine((value) => {
+    try {
+        return new URL(value.trim()).hostname.length > 0;
+    }
+    catch {
+        return false;
+    }
+}, { message: 'must be an https URL with a host' });
+/**
+ * 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, the same three spellings GitHub accepts: a
+ * single remote state, a list, or the full object form with `push` and
+ * `closed`. For Jira the names are workflow status names ("In Progress",
+ * "Done"); `normalizeStatusMappings` 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 jiraConfigSchema = z.object({
+    connection: z.object({
+        /** The Cloud site the project lives on. */
+        site: siteSchema,
+        /** The project key issues are filed into (e.g. `PAY`). */
+        project: z
+            .string({ error: 'connection.project is required' })
+            .min(1, 'connection.project is required')
+            .regex(/^[A-Za-z][A-Za-z0-9_]*$/, 'must be the Jira project key, e.g. PAY'),
+        /**
+         * Agile board id; enables sprint mapping (LP-328). A number in YAML, or a
+         * numeric string — both are the same id.
+         */
+        board: z.union([z.number().int().positive(), z.string().regex(/^\d+$/)])
+            .optional()
+            .transform((value) => (value === undefined ? undefined : String(value))),
+        /**
+         * The account email, written as `${JIRA_EMAIL}` or omitted. Omit and the
+         * resolver (LP-295) looks it up in `.lpm/credentials.json`, then
+         * `JIRA_EMAIL`.
+         */
+        email: z.string().optional(),
+        /**
+         * The API token, written as `${JIRA_API_TOKEN}` or omitted. Omit and the
+         * resolver looks it up in `.lpm/credentials.json`, then `JIRA_API_TOKEN`.
+         */
+        token: z.string().optional(),
+        /**
+         * Explicitly disable TLS verification. Defaults to absent — verification
+         * is on and stays on. A corporate MITM proxy is handled by OS trust-store
+         * injection (NODE_EXTRA_CA_CERTS, `--use-system-ca`); this is the loud,
+         * never-default fallback.
+         */
+        tls_verify: z.boolean().optional(),
+    }),
+    mapping: z.object({
+        /** Board type → the Jira issuetype name it becomes. */
+        types: z
+            .record(z.string(), typeEntrySchema)
+            .default({})
+            .transform((entries) => normalizeTypeMappings(entries)),
+        /** Board status id → the Jira workflow status name(s) and terminal flag. */
+        statuses: z
+            .record(z.string(), statusEntrySchema)
+            .default({})
+            .transform((entries) => normalizeStatusMappings(entries)),
+        /**
+         * How a status change is applied (LP-326). `multi_hop` opts in to walking
+         * the workflow several transitions to reach a status with no direct hop;
+         * it is off by default because transitions fire automations, notify people
+         * and stamp resolutions — the decision is the operator's, not the sync's.
+         */
+        transitions: z
+            .object({
+            multi_hop: z.boolean().optional(),
+        })
+            .optional()
+            .default({}),
+        /**
+         * Values for transition screens, keyed by the Jira field key a transition
+         * requires (`resolution`, `customfield_10016`). A transition whose screen
+         * requires a field is satisfied from here; a required field with no entry
+         * is refused with the field named rather than guessed.
+         */
+        transition_fields: z.record(z.string(), z.unknown()).optional().default({}),
+        /** Board attribute name → the Jira custom field id carrying it. */
+        attributes: z.record(z.string(), z.string().min(1)).default({}),
+        accounts: z
+            .object({
+            /** Resource attribute whose value is the Jira account id. */
+            via: z.string().min(1),
+        })
+            .optional(),
+        /**
+         * How the board's parent chain is carried (LP-309): `sub-issues` uses the
+         * remote's native parent edge where the depth allows, `labels` puts every
+         * parent in the managed block.
+         *
+         * Worth setting on a **team-managed** project, where the answer depends on
+         * the *types* rather than the depth: only a standard issue may sit under an
+         * Epic, and an Epic may not sit under anything. A board with three levels
+         * above its stories maps them all onto `Epic`, and Jira then refuses the
+         * native parent for each of them ("Please select valid parent issue") —
+         * `hierarchy: labels` files the whole chain in the block instead, which is
+         * lossless and round-trips. Absent means the encoding is resolved from the
+         * project's own probed depth, which is right for a company-managed project
+         * with a real type hierarchy.
+         */
+        hierarchy: z.enum(['sub-issues', 'labels']).optional(),
+        periods: z
+            .object({
+            /** The period type that maps to a Jira sprint (`sprint`). */
+            container: z.string().min(1),
+        })
+            // Jira's only native container is a sprint, so the carrier is fixed —
+            // the transform stamps it so `openRemote` / `normalizePeriodMapping`
+            // downstream see `carrier: 'sprint'` rather than the GitHub default.
+            .transform((value) => ({ container: value.container, carrier: 'sprint' }))
+            .optional(),
+    }),
+});
+//# sourceMappingURL=config.js.map

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

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

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

@@ -0,0 +1,42 @@
+/**
+ * The Jira Cloud connector — a live connection to one Cloud site, driven by the
+ * executor (LP-490).
+ *
+ * Built from a validated `connection` block (`site`, `project`, `board`,
+ * `email`, `token`, `tls_verify`). The HTTP and Basic Auth header construction
+ * are owned by the wrapped client — `jira.js`, an optional *peer* dependency
+ * (never installed with light-plan, because Jira sync is experimental) loaded through a computed specifier so the engine still
+ * compiles and runs on a machine that never installed it (exactly the pattern
+ * `runner/pi.ts` uses for the pi SDK). The client lives entirely inside this
+ * file, behind the provider `Connector` contract (LP-289), so the retry/budget
+ * decorators and the conformance suite see an ordinary connector and nothing
+ * here leaks into the planners or core.
+ *
+ * TLS verification is **on by default and stays on**. A corporate MITM proxy
+ * with a custom root CA is handled outside this file — `NODE_EXTRA_CA_CERTS`
+ * or Node's `--use-system-ca` inject the root into the OS trust store that
+ * Node's built-in `fetch` already verifies against. `tls_verify: false` is the
+ * explicit, loud fallback: it warns on every build and is never the default.
+ *
+ * Three failure modes produce three different messages (LP-294's shapes):
+ * a site that cannot be reached (DNS/TLS/non-Jira), an account email the site
+ * rejects, and an API token the site rejects. The email-vs-token distinction
+ * is a documented heuristic on Atlassian's 401 body — both are a 401, and the
+ * message names the most likely fix for each.
+ *
+ * Server/Data Center is out of scope, consistent with the epic's Cloud-first
+ * decision: a URL that answers but has no Cloud v3 API is reported as "not
+ * supported" rather than as a confusing 401 or 404.
+ */
+import type { Connector } from '../../provider.js';
+import { type JiraConnector } from './fields.js';
+import { type JiraSprintConnector } from './sprints.js';
+/**
+ * Build a Jira connector from a validated connection block (and mapping, whose
+ * `transitions` / `transition_fields` shape how a status change is applied).
+ *
+ * `site` and `project` are required (the schema enforces them); `email` and
+ * `token` are the *resolved* secrets (the resolver filled them from the
+ * credential chain before this is called); `tls_verify` defaults to on.
+ */
+export declare function jiraConnector(connection: Record<string, unknown>, mapping?: Record<string, unknown>): Connector & JiraConnector & JiraSprintConnector;