@geneverse/workctl 0.2.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geneverse
+
+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/README.md

@@ -0,0 +1,340 @@
+# workctl
+
+Deterministic internal developer workflows in one CLI. The Time Sync capability
+is available through `workctl jira`.
+
+```bash
+workctl jira sync
+workctl update
+workctl setup
+workctl jenkins job create --help
+workctl assistant status
+```
+
+The npm package contains the compiled CLI, this README, and the MIT license.
+Project planning and architecture notes live in the source repository and are
+not included in the published package.
+
+## jira capability
+
+Deterministic local CLI for synchronizing Kawari timesheets to Jira Cloud.
+No double-entry — scrape your timesheet, review what will be created, and
+approve once.
+
+## Quick Start
+
+**Prerequisites:** Node.js ≥22, a Jira Cloud API token, and access to your
+Kawari timesheet.
+
+```bash
+npm install -g @geneverse/workctl
+workctl browsers install
+workctl setup
+```
+
+The onboarding hub always lets you select setup-capable capabilities and
+requires at least one selection. jira is selected by default; compact
+onboarding asks only for Jira email and API token, supplies the company
+defaults, verifies the result, and writes a private user-global configuration
+file. Re-running setup skips configuration that is already valid and verifies
+it again.
+
+## Configuration
+
+Run `workctl jira configure` to review the current configuration and select
+only the sections you want to edit: Jira credentials, service defaults, or
+Link Status Audit. On macOS and Linux, configuration is stored at
+`~/.config/workctl/config.json`; on Windows, it is stored under
+`%APPDATA%\workctl\config.json`. POSIX directories and files use private
+permissions. The Jira token is stored as plain text in that file, so use
+workctl only on a trusted personal workstation.
+
+| Config field | Environment override | Description |
+|---|---|---|
+| `jiraBaseUrl` | `JIRA_BASE_URL` | Jira Cloud HTTPS origin |
+| `jiraEmail` | `JIRA_EMAIL` | Your Jira account email |
+| `jiraApiToken` | `JIRA_API_TOKEN` | Jira Cloud API token ([create one here](https://id.atlassian.com/manage-profile/security/api-tokens)) |
+| `timesheetUrl` | `TIMESHEET_URL` | Full URL to the Kawari timesheet |
+| `timezone` | `TZ` | Must be `Asia/Bangkok` |
+| `linkAudit.projects` | — | Optional Jira project map with `doneStatuses` for `audit-links` |
+
+Real process environment variables override the config file field by field.
+workctl does not load `.env` files. `NO_COLOR=1` disables colored output.
+
+Use `workctl jira config show` to inspect effective values and their source. The token
+is always redacted. Use `workctl jira doctor` to check permissions, Jira credentials,
+and the Playwright Chromium installation.
+
+## Commands
+
+```
+workctl jira sync    [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--export csv|json]
+workctl jira preview [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--export csv|json]
+workctl jira verify  [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--export csv|json]
+workctl jira rollback [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--issue KEY] [--dry-run]
+workctl jira audit-links [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--export csv|json]
+workctl jira configure
+workctl jira config show
+workctl jira doctor
+workctl browsers install
+workctl update
+```
+
+`workctl setup` selects, compactly configures, and verifies capabilities.
+`workctl jira configure` is the full editor for Jira-specific settings.
+
+| Command | Writes to Jira? | Purpose |
+|---|---|---|
+| `sync` | Yes (with approval) | Full pipeline: scrape, preview, approve, create, verify |
+| `preview` | No | Read-only: scrape and show what would happen |
+| `verify` | No | Compare eligible entries against existing tool-managed Jira worklogs |
+| `rollback` | Yes (typed approval) | Delete matching tool-managed worklogs and restore their time to Remaining Estimate |
+| `audit-links` | No | Audit linked issue statuses for Jira issues found in Kawari |
+| `browsers install` | No | Install the Playwright Chromium browser required by Kawari scraping |
+| `update` | No | Install the latest stable `@geneverse/workctl` release from npm after approval |
+
+### Rolling back a sync
+
+`workctl jira rollback` reads the selected Kawari entries and previews only Jira
+worklogs carrying matching `jlog:v1` Source Identities. The worklog must belong
+to the current Jira account. Type the displayed `delete N` phrase to proceed,
+or use `--dry-run` for a read-only check.
+
+Each deletion sends `adjustEstimate=auto`, so deleting a 2h worklog from an
+issue with 3h remaining restores Remaining Estimate to 5h. The Jira capability does not set
+Original Estimate or an absolute remaining value. Use repeatable
+`--issue OLD-1` options if a source entry's Jira key changed before rollback.
+Once deletion begins, the Jira capability writes a private JSON receipt under
+the local workctl data directory.
+
+**Date range:** interactive `workctl jira sync`, `workctl jira rollback`, and `workctl jira audit-links`
+ask whether to use
+the current calendar month in `Asia/Bangkok` (showing its inclusive dates) or
+enter custom `From` and `To` dates. The current month is selected by default.
+`preview`, `verify`, and non-interactive commands continue to use the current
+month when dates are omitted. Explicit ranges bypass the prompt and must fall
+within one calendar month.
+
+### Auditing linked issue statuses
+
+`workctl jira audit-links` reads Jira keys from Kawari for the selected date range. It
+checks links only for source issues whose current status is configured as done
+for that Jira project. Every unique linked pair is reported as `Mismatch` or
+`Aligned`; completed source issues without links are reported as `No Links`.
+Link type and direction are displayed exactly as Jira returns them.
+
+Configure the Link Audit Scope with `workctl jira configure`. The wizard reads
+accessible projects and their statuses from Jira, then lets you select the
+Done Statuses for each project:
+
+```json
+{
+  "version": 1,
+  "capabilities": {
+    "jira": {
+      "linkAudit": {
+        "projects": {
+          "ABC": {
+            "doneStatuses": ["DONE", "READY TO DEPLOY"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Status comparison ignores surrounding whitespace and letter case. This scope
+does not restrict worklog sync, preview, or verification. Source issues outside
+the scope are skipped and summarized. Cross-project targets use their own
+configured Done Statuses; targets outside the scope are reported as
+`Not Configured`. Invalid Kawari entries and incomplete Jira responses still
+block the audit. Mismatches do not produce a failing exit code, and the command
+never changes Jira. Use `--export csv|json` to retain the complete report,
+including skipped sources and unconfigured targets.
+
+Interactive command output uses one guided terminal presentation for prompts,
+progress, results, and errors. `--help`, `--version`, and non-interactive output
+remain plain text for piping and automation.
+
+**Audit export** (`--export`): writes a timestamped CSV or JSON file to the
+local workctl data directory for your records.
+
+### Updating workctl
+
+Run `workctl update` to check the npm registry for `@geneverse/workctl`. If a
+newer stable version exists, workctl shows the target package, requires you to
+type `yes`, and runs `npm install --global @geneverse/workctl@<version>` without
+`sudo`. This command does not require Jira or Kawari configuration.
+
+You can also update directly with npm:
+
+```bash
+npm update -g @geneverse/workctl
+```
+
+## How It Works
+
+### Pipeline
+
+Each `sync` runs these steps:
+
+1. **Resolve date range** — interactive `sync` offers the displayed current
+   month or a custom range before opening Kawari
+2. **Scrape Kawari** — launches a browser; prompts for manual login if the
+   session expired
+3. **Classify** — each hours cell becomes a Timesheet Entry and is classified as:
+   - **Eligible** — exactly one Jira issue key, ready to sync
+   - **Unmapped** — no Jira key (e.g. internal meetings), skipped with a warning
+   - **Invalid** — bad data, multiple keys, or ambiguous identity
+4. **Read Jira and repair keys** — fetches existing worklogs to check for prior
+   syncs. If a Jira issue does not exist, an interactive run can replace that
+   key for the current batch and validate the replacement immediately.
+5. **Preview** — shows what will be created, skipped, or flagged as a conflict
+6. **Approve** — interactive confirmation before any writes
+7. **Create worklogs** — each new worklog gets a `jlog:v1:` marker in its
+   comment
+8. **Verify** — re-reads Jira to confirm every expected worklog exists
+
+`audit-links` shares date selection, Kawari classification, and temporary
+missing-key repair, but reads Jira link metadata through a separate read-only
+pipeline and never creates or transitions issues.
+
+### Safety Gates
+
+- **Invalid entries** and **sync conflicts** (a previously-synced entry whose
+  values changed) block the entire batch. Nothing is written until all issues
+  are resolved.
+- A Jira key correction is a **Batch Override**. It applies to every affected
+  entry in the current command only; it does not edit Kawari or persist a local
+  mapping. Non-interactive runs fail with repair guidance instead.
+- The approval prompt shows exact counts and hours before you commit.
+
+### Idempotency
+
+Every worklog created by the Jira capability contains a legacy `jlog:v1:` marker — a base64url-encoded
+snapshot of the source entry. On re-runs, entries with a matching marker are
+skipped automatically. The marker survives local state loss and prevents
+duplicates across machines.
+
+## Example
+
+```
+$ workctl jira sync --from 2026-01-05 --to 2026-01-09
+
+──────────────────────────────────────────────────
+  Sync Batch:  2026-01-05 → 2026-01-09
+──────────────────────────────────────────────────
+
+╔═══════════════════════════════════════════════════════╗
+║                     PREVIEW                           ║
+╠═══════════════════════════════════════════════════════╣
+║  Create    3 worklog(s)                    12.0h      ║
+║  Skip      1 worklog(s)                     2.0h      ║
+╠═══════════════════════════════════════════════════════╣
+║  Total eligible                            14.0h      ║
+╚═══════════════════════════════════════════════════════╝
+
+Create 3 Jira worklog(s) totaling 12h? Yes
+
+◇ Ownership rechecked
+│ ╭───────────────────────────────────────────────────╮
+│ │ PROGRESS   DATE         ISSUE      TIME   STATUS  │
+│ ├───────────────────────────────────────────────────┤
+✓ │ 1/3        2026-01-07   PROJ-123   4h     Created │
+✓ │ 2/3        2026-01-08   PROJ-456   4h     Created │
+✓ │ 3/3        2026-01-09   PROJ-789   4h     Created │
+│ ╰───────────────────────────────────────────────────╯
+● Created 3 (12h) · Failed 0 (0h)
+
+Verified: 3 of 3 expected worklogs found on Jira.
+```
+
+## Development
+
+**Prerequisites:** Node.js ≥22, npm, a Jira Cloud API token, and access to the
+Kawari timesheet.
+
+For a fresh clone, bootstrap the project once. This installs npm dependencies
+and Playwright Chromium, then opens the onboarding hub:
+
+```bash
+npm run bootstrap
+```
+
+Run the CLI directly from TypeScript without building or linking it:
+
+```bash
+npm run dev -- jira sync
+npm run dev -- jira preview --from 2026-07-01 --to 2026-07-04
+```
+
+The compiled workflow remains available when testing the packaged executable:
+
+```bash
+npm ci
+npm run build
+npm link
+workctl jira sync
+```
+
+Development checks:
+
+```bash
+npm test            # run tests (vitest)
+npm run typecheck   # type-check only, no emit
+npm run build       # compile TypeScript → dist/
+npm run test:package # pack and install the CLI in a temporary npm prefix
+```
+
+### Releasing
+
+Start from a clean `main` branch, then run the development checks before
+creating a patch release:
+
+```bash
+npm test
+npm run typecheck
+npm run build
+npm run test:package
+npm version patch -m "chore(release): %s"
+git push origin main --follow-tags
+```
+
+`npm version` updates `package.json` and `package-lock.json`, creates the
+release commit, and tags it as `v<version>`. The tag workflow publishes
+`@geneverse/workctl` to the npm registry with public access.
+
+### Project Structure
+
+```
+packages/
+├── cli/                    workctl composition root and binary
+└── capabilities/
+    ├── jira/               Kawari-to-Jira time synchronization
+    ├── jenkins/            Git-backed Jenkins definitions
+    └── assistant/          vendor CLI installation status
+```
+
+Each capability owns its commands, dependencies, implementation, tests, and
+domain glossary. Capabilities are built into one release and cannot import one
+another. The CLI imports only their public entrypoints.
+
+### Local State
+
+Runtime data is user-global. On macOS and Linux it lives under
+`~/.local/share/workctl/jira/`; on Windows it lives under
+`%LOCALAPPDATA%\workctl\jira\`:
+
+- `browser-profile/` — persistent Playwright Chromium session
+- `audit-exports/` — timestamped CSV/JSON exports
+- `state/` — sync state
+
+Run `workctl setup` after installation; the first sync will require Kawari
+login.
+
+Uninstall the CLI with npm:
+
+```bash
+npm uninstall -g @geneverse/workctl
+```

package/dist/packages/capabilities/assistant/src/commands.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+import { type AssistantStatus } from "./status.js";
+export interface AssistantCommandIO {
+    stdout(message: string): void;
+}
+export interface AssistantDependencies {
+    statuses(): Promise<readonly AssistantStatus[]>;
+}
+export declare function createAssistantDependencies(): AssistantDependencies;
+export declare function registerAssistantCommands(program: Command, io: AssistantCommandIO, dependencies?: AssistantDependencies): void;

package/dist/packages/capabilities/assistant/src/commands.js

@@ -0,0 +1,33 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { assistantStatuses } from "./status.js";
+const execFileAsync = promisify(execFile);
+export function createAssistantDependencies() {
+    return {
+        statuses: () => assistantStatuses(async (command) => {
+            try {
+                await execFileAsync("which", [command]);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }),
+    };
+}
+export function registerAssistantCommands(program, io, dependencies = createAssistantDependencies()) {
+    program.command("assistant").description("inspect supported assistant installations")
+        .command("status")
+        .action(async () => {
+        for (const status of await dependencies.statuses()) {
+            io.stdout(`${status.displayName} (${status.command}): ` +
+                `${status.installed ? "installed" : "not installed"}\n`);
+            if (status.installed) {
+                io.stdout(`  Sign in directly with the vendor CLI: ${status.loginCommand}\n`);
+            }
+            io.stdout(`  Vendor documentation: ${status.documentationUrl}\n`);
+        }
+        io.stdout("workctl does not run login commands or read, store, configure, or receipt provider credentials.\n");
+    });
+}
+//# sourceMappingURL=commands.js.map

package/dist/packages/capabilities/assistant/src/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../../../../packages/capabilities/assistant/src/commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,iBAAiB,EAAwB,MAAM,aAAa,CAAC;AAUtE,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C,MAAM,UAAU,2BAA2B;IACzC,OAAO;QACL,QAAQ,EAAE,GAAG,EAAE,CAAC,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;YAClD,IAAI,CAAC;gBACH,MAAM,aAAa,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;gBACxC,OAAO,IAAI,CAAC;YACd,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC,CAAC;KACH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,OAAgB,EAChB,EAAsB,EACtB,eAAsC,2BAA2B,EAAE;IAEnE,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,WAAW,CAAC,2CAA2C,CAAC;SAClF,OAAO,CAAC,QAAQ,CAAC;SACjB,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,KAAK,MAAM,MAAM,IAAI,MAAM,YAAY,CAAC,QAAQ,EAAE,EAAE,CAAC;YACnD,EAAE,CAAC,MAAM,CACP,GAAG,MAAM,CAAC,WAAW,KAAK,MAAM,CAAC,OAAO,KAAK;gBAC7C,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,eAAe,IAAI,CACxD,CAAC;YACF,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;gBACrB,EAAE,CAAC,MAAM,CAAC,2CAA2C,MAAM,CAAC,YAAY,IAAI,CAAC,CAAC;YAChF,CAAC;YACD,EAAE,CAAC,MAAM,CAAC,2BAA2B,MAAM,CAAC,gBAAgB,IAAI,CAAC,CAAC;QACpE,CAAC;QACD,EAAE,CAAC,MAAM,CACP,mGAAmG,CACpG,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/packages/capabilities/assistant/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./commands.js";
+export * from "./status.js";

package/dist/packages/capabilities/assistant/src/index.js

@@ -0,0 +1,3 @@
+export * from "./commands.js";
+export * from "./status.js";
+//# sourceMappingURL=index.js.map

package/dist/packages/capabilities/assistant/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/capabilities/assistant/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

package/dist/packages/capabilities/assistant/src/status.d.ts

@@ -0,0 +1,18 @@
+export type AssistantName = "cursor" | "codex" | "claude";
+export interface AssistantDefinition {
+    name: AssistantName;
+    displayName: string;
+    commands: readonly string[];
+    loginCommand: string;
+    documentationUrl: string;
+}
+export interface AssistantStatus {
+    name: AssistantName;
+    displayName: string;
+    command: string;
+    installed: boolean;
+    loginCommand: string;
+    documentationUrl: string;
+}
+export declare const supportedAssistants: readonly AssistantDefinition[];
+export declare function assistantStatuses(exists?: (command: string) => Promise<boolean>): Promise<readonly AssistantStatus[]>;

package/dist/packages/capabilities/assistant/src/status.js

@@ -0,0 +1,48 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export const supportedAssistants = [
+    {
+        name: "cursor",
+        displayName: "Cursor Agent",
+        commands: ["cursor-agent"],
+        loginCommand: "cursor-agent login",
+        documentationUrl: "https://docs.cursor.com/en/cli/reference/authentication",
+    },
+    {
+        name: "codex",
+        displayName: "OpenAI Codex",
+        commands: ["codex"],
+        loginCommand: "codex login",
+        documentationUrl: "https://developers.openai.com/codex/auth/",
+    },
+    {
+        name: "claude",
+        displayName: "Claude Code",
+        commands: ["claude"],
+        loginCommand: "claude",
+        documentationUrl: "https://docs.anthropic.com/en/docs/claude-code/getting-started",
+    },
+];
+export async function assistantStatuses(exists = async (command) => {
+    try {
+        await execFileAsync("which", [command]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}) {
+    return Promise.all(supportedAssistants.map(async (assistant) => {
+        const command = assistant.commands[0];
+        return {
+            name: assistant.name,
+            displayName: assistant.displayName,
+            command,
+            installed: await exists(command),
+            loginCommand: assistant.loginCommand,
+            documentationUrl: assistant.documentationUrl,
+        };
+    }));
+}
+//# sourceMappingURL=status.js.map

package/dist/packages/capabilities/assistant/src/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../../../../packages/capabilities/assistant/src/status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAqB1C,MAAM,CAAC,MAAM,mBAAmB,GAAmC;IACjE;QACE,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,cAAc;QAC3B,QAAQ,EAAE,CAAC,cAAc,CAAC;QAC1B,YAAY,EAAE,oBAAoB;QAClC,gBAAgB,EAAE,yDAAyD;KAC5E;IACD;QACE,IAAI,EAAE,OAAO;QACb,WAAW,EAAE,cAAc;QAC3B,QAAQ,EAAE,CAAC,OAAO,CAAC;QACnB,YAAY,EAAE,aAAa;QAC3B,gBAAgB,EAAE,2CAA2C;KAC9D;IACD;QACE,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,aAAa;QAC1B,QAAQ,EAAE,CAAC,QAAQ,CAAC;QACpB,YAAY,EAAE,QAAQ;QACtB,gBAAgB,EAAE,gEAAgE;KACnF;CACF,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAAgD,KAAK,EAAE,OAAO,EAAE,EAAE;IAChE,IAAI,CAAC;QACH,MAAM,aAAa,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE;QAC7D,MAAM,OAAO,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAE,CAAC;QACvC,OAAO;YACL,IAAI,EAAE,SAAS,CAAC,IAAI;YACpB,WAAW,EAAE,SAAS,CAAC,WAAW;YAClC,OAAO;YACP,SAAS,EAAE,MAAM,MAAM,CAAC,OAAO,CAAC;YAChC,YAAY,EAAE,SAAS,CAAC,YAAY;YACpC,gBAAgB,EAAE,SAAS,CAAC,gBAAgB;SAC7C,CAAC;IACJ,CAAC,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/packages/capabilities/jenkins/src/commands.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+export interface JenkinsCommandIO {
+    stdout(message: string): void;
+}
+export interface JenkinsDependencies {
+    writeFile(file: string, content: string): Promise<void>;
+}
+export declare function createJenkinsDependencies(): JenkinsDependencies;
+export declare function registerJenkinsCommands(program: Command, io: JenkinsCommandIO, dependencies?: JenkinsDependencies): void;

package/dist/packages/capabilities/jenkins/src/commands.js

@@ -0,0 +1,43 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { createJenkinsJobDefinition, jenkinsDefinitionPath, } from "./definition.js";
+export function createJenkinsDependencies() {
+    return {
+        writeFile: async (file, content) => {
+            await mkdir(path.dirname(file), { recursive: true });
+            await writeFile(file, content, { flag: "wx", mode: 0o644 });
+        },
+    };
+}
+export function registerJenkinsCommands(program, io, dependencies = createJenkinsDependencies()) {
+    const job = program.command("jenkins").description("manage Git-backed Jenkins definitions")
+        .command("job").description("manage Jenkins jobs");
+    job.command("create")
+        .requiredOption("--name <name>")
+        .requiredOption("--repo <url>")
+        .option("--branch <branch>", "SCM branch", "main")
+        .requiredOption("--target-host <host>")
+        .requiredOption("--credential-id <id>")
+        .option("--output <directory>", "definition directory", "jenkins/jobs")
+        .option("--write", "write the reviewed definition; otherwise preview only")
+        .action(async (options) => {
+        const input = {
+            name: options.name,
+            repositoryUrl: options.repo,
+            branch: options.branch,
+            targetHost: options.targetHost,
+            credentialId: options.credentialId,
+        };
+        const definition = createJenkinsJobDefinition(input);
+        const destination = jenkinsDefinitionPath(options.output, options.name);
+        io.stdout(`${definition}\nDestination: ${destination}\n`);
+        if (options.write) {
+            await dependencies.writeFile(destination, definition);
+            io.stdout("Definition written. Review and commit it through the normal Git workflow.\n");
+        }
+        else {
+            io.stdout("Preview only; pass --write to create the file.\n");
+        }
+    });
+}
+//# sourceMappingURL=commands.js.map

package/dist/packages/capabilities/jenkins/src/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../../../../packages/capabilities/jenkins/src/commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,GAEtB,MAAM,iBAAiB,CAAC;AAUzB,MAAM,UAAU,yBAAyB;IACvC,OAAO;QACL,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;YACjC,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACrD,MAAM,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9D,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,OAAgB,EAChB,EAAoB,EACpB,eAAoC,yBAAyB,EAAE;IAE/D,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,WAAW,CAAC,uCAAuC,CAAC;SACxF,OAAO,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,qBAAqB,CAAC,CAAC;IACrD,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC;SAClB,cAAc,CAAC,eAAe,CAAC;SAC/B,cAAc,CAAC,cAAc,CAAC;SAC9B,MAAM,CAAC,mBAAmB,EAAE,YAAY,EAAE,MAAM,CAAC;SACjD,cAAc,CAAC,sBAAsB,CAAC;SACtC,cAAc,CAAC,sBAAsB,CAAC;SACtC,MAAM,CAAC,sBAAsB,EAAE,sBAAsB,EAAE,cAAc,CAAC;SACtE,MAAM,CAAC,SAAS,EAAE,uDAAuD,CAAC;SAC1E,MAAM,CAAC,KAAK,EAAE,OAQd,EAAE,EAAE;QACH,MAAM,KAAK,GAAoB;YAC7B,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,aAAa,EAAE,OAAO,CAAC,IAAI;YAC3B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,YAAY,EAAE,OAAO,CAAC,YAAY;SACnC,CAAC;QACF,MAAM,UAAU,GAAG,0BAA0B,CAAC,KAAK,CAAC,CAAC;QACrD,MAAM,WAAW,GAAG,qBAAqB,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QACxE,EAAE,CAAC,MAAM,CAAC,GAAG,UAAU,kBAAkB,WAAW,IAAI,CAAC,CAAC;QAC1D,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,MAAM,YAAY,CAAC,SAAS,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;YACtD,EAAE,CAAC,MAAM,CAAC,6EAA6E,CAAC,CAAC;QAC3F,CAAC;aAAM,CAAC;YACN,EAAE,CAAC,MAAM,CAAC,kDAAkD,CAAC,CAAC;QAChE,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/packages/capabilities/jenkins/src/definition.d.ts

@@ -0,0 +1,10 @@
+export interface JenkinsJobInput {
+    name: string;
+    repositoryUrl: string;
+    branch: string;
+    targetHost: string;
+    credentialId: string;
+}
+export declare function validateJenkinsJobInput(input: JenkinsJobInput): void;
+export declare function createJenkinsJobDefinition(input: JenkinsJobInput): string;
+export declare function jenkinsDefinitionPath(outputDirectory: string, name: string): string;

package/dist/packages/capabilities/jenkins/src/definition.js

@@ -0,0 +1,59 @@
+import path from "node:path";
+const SAFE_NAME = /^[a-z0-9][a-z0-9._-]*$/i;
+const SAFE_CREDENTIAL_ID = /^[a-z0-9][a-z0-9._-]*$/i;
+function xml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
+export function validateJenkinsJobInput(input) {
+    if (!SAFE_NAME.test(input.name))
+        throw new Error("Job name contains unsupported characters.");
+    if (!/^https:\/\/[^/\s]+\/.+/.test(input.repositoryUrl) && !/^git@[^:\s]+:.+/.test(input.repositoryUrl)) {
+        throw new Error("Repository URL must use HTTPS or Git SSH syntax.");
+    }
+    if (!input.branch.trim())
+        throw new Error("Branch is required.");
+    if (!/^[a-z0-9][a-z0-9.-]*$/i.test(input.targetHost)) {
+        throw new Error("Target host must be a hostname or IPv4 address without credentials.");
+    }
+    if (!SAFE_CREDENTIAL_ID.test(input.credentialId)) {
+        throw new Error("Credential ID contains unsupported characters.");
+    }
+}
+export function createJenkinsJobDefinition(input) {
+    validateJenkinsJobInput(input);
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<flow-definition plugin="workflow-job">
+  <description>Managed by workctl. Do not edit in Jenkins.</description>
+  <keepDependencies>false</keepDependencies>
+  <properties/>
+  <definition class="org.jenkinsci.plugins.workflow.cps.CpsScmFlowDefinition" plugin="workflow-cps">
+    <scm class="hudson.plugins.git.GitSCM" plugin="git">
+      <configVersion>2</configVersion>
+      <userRemoteConfigs>
+        <hudson.plugins.git.UserRemoteConfig>
+          <url>${xml(input.repositoryUrl)}</url>
+          <credentialsId>${xml(input.credentialId)}</credentialsId>
+        </hudson.plugins.git.UserRemoteConfig>
+      </userRemoteConfigs>
+      <branches><hudson.plugins.git.BranchSpec><name>*/${xml(input.branch)}</name></hudson.plugins.git.BranchSpec></branches>
+    </scm>
+    <scriptPath>Jenkinsfile</scriptPath>
+    <lightweight>true</lightweight>
+  </definition>
+  <disabled>false</disabled>
+  <actions/>
+  <workctlTargetHost>${xml(input.targetHost)}</workctlTargetHost>
+</flow-definition>
+`;
+}
+export function jenkinsDefinitionPath(outputDirectory, name) {
+    if (!SAFE_NAME.test(name))
+        throw new Error("Job name contains unsupported characters.");
+    return path.join(outputDirectory, `${name}.xml`);
+}
+//# sourceMappingURL=definition.js.map

package/dist/packages/capabilities/jenkins/src/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","sourceRoot":"","sources":["../../../../../packages/capabilities/jenkins/src/definition.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAU7B,MAAM,SAAS,GAAG,yBAAyB,CAAC;AAC5C,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AAErD,SAAS,GAAG,CAAC,KAAa;IACxB,OAAO,KAAK;SACT,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC;SACxB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC;SACvB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC;SACvB,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC;SACzB,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,KAAsB;IAC5D,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC9F,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC;QACxG,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACjE,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;IACpE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,KAAsB;IAC/D,uBAAuB,CAAC,KAAK,CAAC,CAAC;IAC/B,OAAO;;;;;;;;;;iBAUQ,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC;2BACd,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC;;;yDAGO,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC;;;;;;;uBAOnD,GAAG,CAAC,KAAK,CAAC,UAAU,CAAC;;CAE3C,CAAC;AACF,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,eAAuB,EAAE,IAAY;IACzE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IACxF,OAAO,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,GAAG,IAAI,MAAM,CAAC,CAAC;AACnD,CAAC"}

package/dist/packages/capabilities/jenkins/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./commands.js";
+export * from "./definition.js";

package/dist/packages/capabilities/jenkins/src/index.js

@@ -0,0 +1,3 @@
+export * from "./commands.js";
+export * from "./definition.js";
+//# sourceMappingURL=index.js.map

package/dist/packages/capabilities/jenkins/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/capabilities/jenkins/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC"}

package/dist/packages/capabilities/jira/src/adapters/filesystem/config.store.d.ts

@@ -0,0 +1,2 @@
+import type { AppConfig } from "../../config.js";
+export declare function writeConfigAtomic(configPath: string, config: AppConfig): Promise<void>;