@keystrokehq/cli 0.0.1

package/AGENTS-blurb.md

@@ -0,0 +1,123 @@
+# Keystroke Project Context
+
+You are working inside a Keystroke project. Keystroke is a code-first workflow and agent automation platform. Authors define workflows, agents, operations, tasks, triggers, messaging gateways, MCP servers, sandboxes, and credential bindings in TypeScript, then build and deploy them with the Keystroke CLI.
+
+When reasoning about authored code, use this top-level split:
+
+- A `Workflow` is deterministic orchestration. Its `run(...)` method coordinates steps, child workflows, waits, hooks, and agents.
+- An `Agent` is model-driven execution. It runs with agent tools, can use sandboxes, MCP servers, and messaging gateways, and is the right place for llm driven work.
+- A `Task` is the trigger-driven agent path. It combines triggers, a prompt, and an agent run.
+- A workflow can also be registered as an agent tool. Sync workflow tools return inline results; suspending workflow tools yield and resume later; large outputs can return refs inspected with bounded data toolkit tools.
+
+Triggers, tasks, and agent conversations are different entry models:
+
+- a workflow is started by a trigger or direct invocation
+- a trigger is a code-based primitive you author in TypeScript and attach to a workflow
+- a trigger attaches to a workflow and resolves external payload into validated workflow input
+- a trigger is not a chat session; it is an ingress boundary that transforms payload and starts a workflow
+- a task is not attached with `trigger.attach(...)`; it lists triggers inline and resolves a prompt for an agent run
+- an agent conversation is a chat session, not a code-authored primitive like `CronTrigger`, `WebhookTrigger`, or `PollingTrigger`
+- conversations can be started from the UI, from messaging adapters such as Slack, Linear, or GitHub, or from a workflow when the workflow runs an agent
+- messaging gateways configure conversational entry on agents; they are not workflow triggers
+- an agent keeps full context of the conversation session while the workflow side stays replay-safe and stateless between execution boundaries
+
+Keystroke also has one shared unit-of-work primitive: `Operation`.
+
+- `Operation`, `Step`, and `Tool` are aliases for the same class from `@keystroke/workflow-core`.
+- Use the `Step` name when teaching workflow-side usage.
+- Use the `Tool` name when teaching agent-side usage.
+- Use the `Operation` name when describing shared infrastructure, integrations, or a reusable unit that can be used in both places.
+- The runtime behavior comes from context, not from which alias name was used in the constructor.
+
+Runtime boundary:
+
+- workflows and steps are authored as TypeScript control-flow and unit-of-work code
+- workflows do not run bash commands as part of the workflow authoring model
+- agents are the correct place for bash, filesystem work, and sandbox-managed dependencies such as Python
+
+Keystroke workflow execution is replay-based and stateless at the workflow layer:
+
+- Keystroke does not persist live in-memory workflow state.
+- Instead, it persists execution events and terminal results for execution boundaries, then replays the workflow code from the top with that saved state.
+- The workflow body itself is re-executed during replay. Local variables and control flow are recomputed, not resumed from memory.
+- Because of that, workflow code must be replay-safe and deterministic.
+
+Treat these calls inside `Workflow.run(...)` as execution boundaries:
+
+- `await step.run(...)`
+- `await operation.run(...)`
+- `await childWorkflow.run(...)`
+- `await agent.run(...)`
+
+What gets persisted:
+
+- For steps, Keystroke persists created/completed/failed state and reuses the saved result during workflow replay.
+- For child workflows, Keystroke persists the child run and its terminal result, then resumes the parent workflow with that saved outcome.
+- For agents, Keystroke persists agent execution state and terminal output, then resumes the workflow with that saved result.
+- The workflow's own in-memory logic is not persisted. The platform saves boundary state, not the live workflow stack.
+
+Where code runs:
+
+- Operations used as workflow steps are low-level units of work and run in separate worker executions.
+- Child workflows run as separate workflow executions in their own workers, using the same replay model as parent workflows.
+- Agents run outside the workflow replay worker. They run in persisted sandboxes with a persistent filesystem, where they can use files, shell commands, installed skills, MCP servers, and other runtime tools. The filesystem persists over all agent runs for a deployed agent.
+- Operations used as agent tools are not top-level orchestration units. A tool runs inside the agent runtime when the agent chooses to call it, inside that persisted sandbox context.
+
+Workflow triggers versus agent conversations:
+
+- use code-authored triggers when external schedules, webhook requests, or polling results should become workflow input
+- use agent conversations when a user or system is chatting with an agent over time
+- author triggers in code; do not think of conversations as authored primitives in the same way
+- messaging adapters normalize inbound events into thread-based conversations, and the agent responds inside that conversation context
+- a workflow can still start an agent-backed conversation by running an agent, but that is different from a workflow trigger boundary
+
+Authoring implications:
+
+- Put orchestration, branching, loops, waits, and composition in workflows.
+- Put deterministic side effects and integration calls in operations used as steps.
+- Put LLM-driven reasoning and tool selection in agents.
+- Put concrete callable actions in operations used as tools.
+- Use `largeResultMode: 'ref'` plus `describe_ref`, `read_ref`, and `slice_ref` for large workflow-tool outputs. Reducers and DuckDB-backed data tools are deferred.
+- Use `midSessionSnapshot: true` only for measured workflow-tool cases that need Phase D replay. Current snapshot behavior is conversation-log replay, not native Pi process restore.
+- Do not depend on workflow-local mutable state, random values, direct network I/O, or filesystem mutations in the workflow body itself unless they happen behind a Keystroke execution boundary.
+- Never assume workflow-local memory or filesystem state survives between replays. If state must survive, return it from an operation, agent, or child workflow, or persist it externally.
+
+## Workflow Builder File Structure
+
+The workflow builder now relies on explicit file structure. Teach and author Keystroke code with one exported primitive per typed file:
+
+- `*.workflow.ts` for one `Workflow`
+- `*.step.ts`, `*.tool.ts`, or `*.operation.ts` for one exported `Operation`
+- `*.agent.ts` for one `Agent`
+- `*.gateway.ts` for one `MessagingGateway`
+- `*.trigger.ts` for one trigger
+- `*.credential-set.ts` for one `CredentialSet`
+- `*.mcp-server.ts` for one `McpServer`
+
+Builder note:
+
+- `*.step.ts`, `*.tool.ts`, and `*.operation.ts` all validate as the same operation convention
+- choose the suffix that communicates intent to the reader
+
+Required structure:
+
+- exported primitives should be top-level and statically visible
+- helper files such as `schemas.ts`, `utils.ts`, or `prompts.ts` should not export primitives
+- a `*.trigger.ts` file may also export that trigger's `TriggerAttachment` values
+- tests are exempt, but authored project code should follow the typed-file convention everywhere
+
+Example layout:
+
+```text
+customer-support/
+  crm-api.credential-set.ts
+  lookup-customer.tool.ts
+  support.agent.ts
+  support.gateway.ts
+  triage.step.ts
+  support.workflow.ts
+  support.trigger.ts
+  coding.sandbox.ts
+  docs.mcp-server.ts
+  schemas.ts
+```

package/LICENSE

@@ -0,0 +1,42 @@
+MIT License
+
+Copyright (c) 2026 Keystroke
+
+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.
+MIT License
+
+Copyright (c) Keystroke
+
+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,177 @@
+# @keystrokehq/cli
+
+The Keystroke CLI helps you create, build, test, and deploy Keystroke automation projects from your terminal.
+
+Keystroke is a code-first automation platform: you write TypeScript workflows, agents, operations, triggers, and credential bindings, then use the CLI to connect services and deploy the project to Keystroke.
+
+## Install
+
+```bash
+npm install -g @keystrokehq/cli
+keystroke --help
+```
+
+You can also run the latest published version without installing it globally:
+
+```bash
+npx @keystrokehq/cli@latest --help
+```
+
+To test a local packed build without replacing your global `keystroke` install, create or update the
+`keystroke-dev` command:
+
+```bash
+pnpm --filter @keystrokehq/cli run dev:install-pack
+keystroke-dev --help
+```
+
+This installs the packed tarball under `~/.keystroke-dev-cli` and symlinks `keystroke-dev` into
+`~/.local/bin`. Set `KEYSTROKE_DEV_CLI_PREFIX` or `KEYSTROKE_DEV_CLI_BIN_DIR` to override those paths.
+
+## Quick Start
+
+```bash
+# Sign in with Keystroke
+keystroke auth
+
+# Create a project in the current directory
+keystroke init
+
+# Build workflows and agents locally
+keystroke workflows build
+
+# Deploy the current project
+keystroke deploy
+```
+
+Most project commands auto-discover `keystroke.config.ts` from the current working directory. Pass `--path <dir>` when you want to run against another project directory.
+
+## Authentication
+
+Start the device flow:
+
+```bash
+keystroke auth
+```
+
+Then check or clear local credentials:
+
+```bash
+keystroke auth status
+keystroke auth test
+keystroke auth clear
+```
+
+For automation, you can provide credentials through environment variables or root options:
+
+```bash
+KEYSTROKE_API_KEY=sk_... keystroke deploy
+keystroke --api-key sk_... --base-url https://api.example.com workflows list
+```
+
+## Common Commands
+
+| Command | Purpose |
+| --- | --- |
+| `keystroke auth` | Sign in, inspect, test, or clear local CLI credentials. |
+| `keystroke init` | Create a Keystroke project and scaffold starter files. |
+| `keystroke deploy` | Build and deploy the current project snapshot. |
+| `keystroke workflows` | List, build, inspect, validate, diff, test, and read workflow logs. |
+| `keystroke agents inspect` | Inspect built agent manifests and workflow-tool metadata. |
+| `keystroke test` | Test workflows and agent-callable tools. |
+| `keystroke connect` | Connect official integrations through OAuth. |
+| `keystroke integrations` | List available integrations and registration metadata. |
+| `keystroke credentials` | List credential sets, inspect requirements, and upload credential values. |
+| `keystroke org` | View and switch organization context. |
+| `keystroke projects` | List or clear locally tracked projects. |
+| `keystroke runs inspect` | Inspect workflow and agent runs. |
+| `keystroke logs` | View or clear local CLI logs. |
+| `keystroke skills sync` | Sync installed Keystroke agent skills into editor skill folders. |
+
+Run `keystroke <command> --help` for exact arguments and flags.
+
+## Project Workflow
+
+Create a new project:
+
+```bash
+keystroke init --path ./my-automation --name my-automation
+```
+
+Build locally:
+
+```bash
+keystroke workflows build --path ./my-automation
+```
+
+Inspect what will be deployed:
+
+```bash
+keystroke workflows list --path ./my-automation
+keystroke workflows inspect <workflow-id-or-name> --path ./my-automation
+keystroke workflows diff <workflow-id-or-name> --path ./my-automation
+```
+
+Deploy:
+
+```bash
+keystroke deploy --path ./my-automation
+keystroke deploy --dry-run --path ./my-automation
+keystroke deploy --diff --path ./my-automation
+```
+
+Test a workflow or agent tool:
+
+```bash
+keystroke test workflow <workflow-id-or-name> --input '{"example":true}'
+keystroke test tool <tool-name> --agent <agent-id-or-name> --input-file ./input.json
+```
+
+## Configuration
+
+The CLI reads configuration from, in order:
+
+1. Command-line flags such as `--api-key`, `--base-url`, `--org`, and command-specific options.
+2. Environment variables such as `KEYSTROKE_API_KEY`, `SERVER_URL`, `WEB_URL`, and `KEYSTROKE_ORG_ID`.
+3. Credentials saved by `keystroke auth`.
+4. Project configuration in `keystroke.config.ts`.
+
+Use `--debug` on any command to show diagnostic output.
+
+## Integrations And Credentials
+
+Connect an OAuth integration:
+
+```bash
+keystroke connect slack
+keystroke connect linear
+keystroke connect shopify --shop example.myshopify.com
+```
+
+Inspect integration and credential state:
+
+```bash
+keystroke integrations list
+keystroke credentials requirements --path .
+keystroke credentials list
+```
+
+Upload credentials from environment variables required by your built manifests:
+
+```bash
+keystroke credentials upload --path .
+```
+
+## Telemetry
+
+CLI telemetry is off by default.
+
+Set `KEYSTROKE_TELEMETRY=1` to enable one usage event per invocation. Events include command id, CLI version, exit code, duration, OS/architecture, and coarse failure category. They do not include raw argv, secrets, workflow names, or credential values.
+
+In CI, telemetry is enabled only when `KEYSTROKE_TELEMETRY=1`.
+
+## Support
+
+- Issues: <https://github.com/keystrokehq/keystroke/issues>
+- Package: <https://www.npmjs.com/package/@keystrokehq/cli>
+- License: MIT

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,16 @@
+# Third-party notices
+
+The `@keystrokehq/cli` package depends on third-party open source software. Each dependency is licensed under the terms published with that package on npm. Transitive dependencies are likewise licensed by their respective authors.
+
+Direct runtime dependencies:
+
+- `@clack/prompts` — MIT
+- `cli-table3` — MIT
+- `commander` — MIT
+- `dayjs` — MIT
+- `dotenv` — BSD-2-Clause
+- `ky` — MIT
+- `oxc-parser` — MIT
+- `rolldown` — MIT
+- `tsx` — MIT
+- `zod` — MIT

package/bin/keystroke.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const argv = process.argv.slice(2);
+const rootOptionsWithValues = new Set(['--api-key', '--base-url', '--org']);
+const deployTargetOptionsWithValues = new Set(['--path', '--target']);
+const optionsWithValues = new Set([...rootOptionsWithValues, ...deployTargetOptionsWithValues]);
+
+function optionValue(name) {
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === name) return argv[index + 1];
+    if (arg?.startsWith(`${name}=`)) return arg.slice(name.length + 1);
+  }
+  return undefined;
+}
+
+function hasFlag(name) {
+  return argv.includes(name);
+}
+
+function commandTokens() {
+  const tokens = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg) continue;
+    if (arg === '--') break;
+    if (arg.startsWith('--')) {
+      const [flag] = arg.split('=', 1);
+      if (flag && optionsWithValues.has(flag) && !arg.includes('=')) {
+        index += 1;
+      }
+      continue;
+    }
+    if (arg.startsWith('-')) continue;
+    tokens.push(arg);
+  }
+  return tokens;
+}
+
+function collectValues(name) {
+  const values = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === name) {
+      const value = argv[index + 1];
+      if (value) values.push(value);
+      index += 1;
+      continue;
+    }
+    if (arg?.startsWith(`${name}=`)) {
+      values.push(arg.slice(name.length + 1));
+    }
+  }
+  return values;
+}
+
+function replaceProcessOrSpawn(file, args, env) {
+  if (process.execve) {
+    process.execve(file, args, env);
+    throw new Error('process.execve returned unexpectedly.');
+  }
+  const result = spawnSync(file, args.slice(1), { stdio: 'inherit', env });
+  if (result.error) throw result.error;
+  process.exit(result.status ?? 1);
+}
+
+function tryRunTaskTargetDeployFastPath() {
+  const [command] = commandTokens();
+  const targets = collectValues('--target');
+  if (command !== 'deploy' || targets.length === 0) {
+    return;
+  }
+  if (!targets.every((target) => target.endsWith('.task.ts'))) {
+    return;
+  }
+
+  const here = dirname(fileURLToPath(import.meta.url));
+  const runnerPath = resolve(here, '../dist/task-target-deploy-runner.mjs');
+  const pathValue = optionValue('--path');
+  const apiKey = optionValue('--api-key');
+  const baseUrl = optionValue('--base-url');
+  const org = optionValue('--org');
+  const runnerArgs = [
+    process.execPath,
+    ...process.execArgv,
+    runnerPath,
+    ...(pathValue ? ['--path', pathValue] : []),
+    ...(hasFlag('--force') ? ['--force'] : []),
+    ...(hasFlag('--dry-run') ? ['--dry-run'] : []),
+    ...(hasFlag('--disable-sourcemaps') ? ['--disable-sourcemaps'] : []),
+    ...(apiKey ? ['--api-key', apiKey] : []),
+    ...(baseUrl ? ['--base-url', baseUrl] : []),
+    ...(org ? ['--org', org] : []),
+    ...targets.flatMap((target) => ['--target', target]),
+  ];
+
+  replaceProcessOrSpawn(process.execPath, runnerArgs, {
+    // biome-ignore lint/style/noProcessEnv: bin fast path preserves caller environment
+    ...process.env,
+  });
+}
+
+tryRunTaskTargetDeployFastPath();
+import '../dist/keystroke.mjs';