studiometa
diff --git a/‎CHANGELOG.md‎
Lines changed: 19 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 19 additions & 0 deletions
diff --git a/‎package-lock.json‎
Lines changed: 2 additions & 1 deletion b/‎package-lock.json‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎packages/cli/examples/README.md‎
Lines changed: 52 additions & 0 deletions b/‎packages/cli/examples/README.md‎
Lines changed: 52 additions & 0 deletions
diff --git a/‎packages/cli/examples/log-time.ts‎
Lines changed: 69 additions & 0 deletions b/‎packages/cli/examples/log-time.ts‎
Lines changed: 69 additions & 0 deletions
diff --git a/‎packages/cli/examples/my-tasks.ts‎
Lines changed: 51 additions & 0 deletions b/‎packages/cli/examples/my-tasks.ts‎
Lines changed: 51 additions & 0 deletions
diff --git a/‎packages/cli/examples/project-list.ts‎
Lines changed: 60 additions & 0 deletions b/‎packages/cli/examples/project-list.ts‎
Lines changed: 60 additions & 0 deletions
diff --git a/‎packages/cli/examples/time-report.ts‎
Lines changed: 71 additions & 0 deletions b/‎packages/cli/examples/time-report.ts‎
Lines changed: 71 additions & 0 deletions
diff --git a/‎packages/cli/package.json‎
Lines changed: 6 additions & 1 deletion b/‎packages/cli/package.json‎
Lines changed: 6 additions & 1 deletion
@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **CLI**: Add `productive run` (alias `productive script`) command to execute JS/TS scripts with a pre-configured Productive SDK client injected automatically ([ff1e486], [#173])
+- **CLI**: Export `@studiometa/productive-cli/script` subpath with `ScriptContext`, `ScriptOutput`, `ScriptSpinner` types and `createScriptOutput()` factory for testing scripts in isolation ([ff1e486], [#173])
+- **CLI**: Add `@studiometa/productive-sdk` as a dependency so `productive run` can inject the SDK client into user scripts without additional installation ([ff1e486], [#173])
+- **CLI**: Add parsed `flags` object to `ScriptContext` — named flags like `--from 2025-01-01 --mine` are parsed and available as `flags.from` and `flags.mine` alongside positional `args` ([c432a57], [#173])
+- **CLI**: Add wrap-style `output.spinner(msg, asyncFn)` overload — spinner starts and auto-stops when the async task resolves or fails ([2de17c8], [#173])
+- **CLI**: Enable `--enable-source-maps` in `productive run` subprocess so TypeScript stack traces show original line numbers from the stripped output ([f1074c2], [#173])
+- **CLI**: Add `--dry-run` flag to `productive run` — intercepts mutating API calls (POST/PATCH/PUT/DELETE) via a `globalThis.fetch` wrapper, records them without executing, and prints a summary table ([4068429], [#173])
+- **CLI**: Add `export const meta: ScriptMeta` convention and `productive run --list [dir]` for script discovery — lists `.ts`/`.js` files in a directory with name, description, and usage from each script's `meta` export ([db674cd], [#173])
+
+[ff1e486]: https://github.com/studiometa/productive-tools/commit/ff1e486
+[c432a57]: https://github.com/studiometa/productive-tools/commit/c432a57
+[2de17c8]: https://github.com/studiometa/productive-tools/commit/2de17c8
+[f1074c2]: https://github.com/studiometa/productive-tools/commit/f1074c2
+[4068429]: https://github.com/studiometa/productive-tools/commit/4068429
+[db674cd]: https://github.com/studiometa/productive-tools/commit/db674cd
+[#173]: https://github.com/studiometa/productive-tools/pull/173
+
 ## [0.10.11] - 2026.05.19
 
 ### Added
 
@@ -0,0 +1,52 @@
+# productive run — examples
+
+Ready-to-run script examples for `productive run`. Copy any file to your own
+`scripts/` directory and adjust as needed.
+
+## Running an example
+
+```bash
+# From the repo root (using the built CLI)
+productive run packages/cli/examples/my-tasks.ts
+
+# Pass flags
+productive run packages/cli/examples/time-report.ts --from 2025-01-01 --to 2025-01-31
+
+# Preview mutations without executing them
+productive run --dry-run packages/cli/examples/log-time.ts --service-id 12345 --hours 2
+```
+
+## Examples
+
+| File                                   | Description                                              |
+| -------------------------------------- | -------------------------------------------------------- |
+| [`my-tasks.ts`](./my-tasks.ts)         | List open tasks assigned to you, with optional `--limit` |
+| [`time-report.ts`](./time-report.ts)   | Export time entries for a date range to CSV              |
+| [`log-time.ts`](./log-time.ts)         | Log a time entry for today (or a custom date)            |
+| [`project-list.ts`](./project-list.ts) | List active projects, optionally including archived ones |
+
+## Authoring your own scripts
+
+```typescript
+import { defineMeta, createScript } from '@studiometa/productive-cli/script';
+
+export const meta = defineMeta({
+  name: 'My Script',
+  description: 'One-line description shown by productive run --list.',
+  usage: '[--flag <value>]',
+});
+
+export default createScript(async ({ client, output, flags }) => {
+  // client   → pre-configured Productive SDK client
+  // output   → output.table(), .csv(), .json(), .spinner(), .info(), …
+  // flags    → parsed flags: --from 2025-01-01 → flags.from === '2025-01-01'
+  // args     → positional args after the script path
+});
+```
+
+SDK tips:
+
+- `.all({ filter: { … } }).toArray()` — fetch all pages into an array
+- `.list({ filter: { … } })` — fetch a single page (returns `{ data, meta }`)
+- All resource types use flat attribute access: `task.title`, not `task.attributes.title`
+- `process.env.PRODUCTIVE_USER_ID` — the authenticated user's ID (injected automatically)
@@ -0,0 +1,69 @@
+/**
+ * Log a time entry for today (or a custom date).
+ *
+ * Requires a service ID — find one with: productive services list
+ *
+ * Usage:
+ *   productive run examples/log-time.ts --service-id <id> --hours 2
+ *   productive run examples/log-time.ts --service-id <id> --hours 1.5 --note "Fixed login bug"
+ *   productive run examples/log-time.ts --service-id <id> --hours 3 --date 2025-01-15
+ *
+ *   # Preview without creating anything:
+ *   productive run --dry-run examples/log-time.ts --service-id <id> --hours 2
+ *
+ * Flags:
+ *   --service-id <id>   Service (budget line) to log time against, required
+ *   --hours <n>         Hours to log (decimals ok: 1.5 = 1h30), required
+ *   --note <text>       Optional note for the time entry
+ *   --date <YYYY-MM-DD> Date to log for (default: today)
+ */
+
+import { createScript, defineMeta } from '@studiometa/productive-cli/script';
+
+export const meta = defineMeta({
+  name: 'Log Time',
+  description: 'Log a time entry for today or a custom date.',
+  usage: '--service-id <id> --hours <n> [--note <text>] [--date <YYYY-MM-DD>]',
+});
+
+export default createScript(async ({ client, output, flags }) => {
+  const serviceId = flags['service-id'] as string | undefined;
+  const hoursRaw = flags.hours as string | number | undefined;
+  const note = flags.note as string | undefined;
+  const date = (flags.date as string | undefined) ?? new Date().toISOString().slice(0, 10);
+
+  if (!serviceId) {
+    output.error('--service-id is required. Find service IDs with: productive services list');
+    process.exit(1);
+  }
+  if (hoursRaw == null) {
+    output.error('--hours is required. Example: --hours 2 or --hours 1.5');
+    process.exit(1);
+  }
+
+  const hours = Number(hoursRaw);
+  if (Number.isNaN(hours) || hours <= 0) {
+    output.error(`Invalid --hours value: "${hoursRaw}". Must be a positive number.`);
+    process.exit(1);
+  }
+
+  const minutes = Math.round(hours * 60);
+  const personId = process.env.PRODUCTIVE_USER_ID;
+
+  if (!personId) {
+    output.error('PRODUCTIVE_USER_ID is not set. Run: productive whoami');
+    process.exit(1);
+  }
+
+  const spin = output.spinner(`Logging ${hours}h on service ${serviceId} for ${date}…`);
+
+  const entry = await client.time
+    .create({ person_id: personId, service_id: serviceId, date, time: minutes, note })
+    .catch((err: unknown) => {
+      spin.fail(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    });
+
+  spin.stop(`Logged ${hours}h (entry #${entry.data.id})`);
+  output.success(`${hours}h logged on ${date}${note ? ` — "${note}"` : ''}`);
+});
@@ -0,0 +1,51 @@
+/**
+ * List open tasks assigned to the current user.
+ *
+ * Usage:
+ *   productive run examples/my-tasks.ts
+ *   productive run examples/my-tasks.ts --limit 10
+ *   productive run examples/my-tasks.ts --limit 50 --overdue-only
+ */
+
+import { createScript, defineMeta } from '@studiometa/productive-cli/script';
+
+export const meta = defineMeta({
+  name: 'My Tasks',
+  description: 'List open tasks assigned to you.',
+  usage: '[--limit <n>] [--overdue-only]',
+});
+
+export default createScript(async ({ client, output, flags }) => {
+  const limit = flags.limit ? Number(flags.limit) : 20;
+  const overdueOnly = flags['overdue-only'] === true;
+
+  const tasks = await output.spinner('Fetching tasks…', () =>
+    client.tasks
+      .all({ filter: { assignee_id: process.env.PRODUCTIVE_USER_ID, status: '1' } })
+      .toArray(),
+  );
+
+  const today = new Date().toISOString().slice(0, 10);
+
+  const filtered = overdueOnly
+    ? tasks.filter((t) => t.due_date != null && t.due_date < today)
+    : tasks;
+
+  if (filtered.length === 0) {
+    output.info(overdueOnly ? 'No overdue tasks — nice work!' : 'No open tasks assigned to you.');
+    return;
+  }
+
+  output.table(
+    filtered.slice(0, limit).map((t) => ({
+      id: t.id,
+      title: t.title,
+      due: t.due_date ?? '—',
+      overdue: t.due_date != null && t.due_date < today ? '⚠' : '',
+    })),
+  );
+
+  if (filtered.length > limit) {
+    output.info(`Showing ${limit} of ${filtered.length} tasks. Increase --limit to see more.`);
+  }
+});
@@ -0,0 +1,60 @@
+/**
+ * List active projects, with optional search and format flags.
+ *
+ * Usage:
+ *   productive run examples/project-list.ts
+ *   productive run examples/project-list.ts --include-archived
+ *   productive run examples/project-list.ts --search "website"
+ *   productive run examples/project-list.ts --format json
+ *
+ * Flags:
+ *   --search <term>      Filter projects by name (case-insensitive substring match)
+ *   --include-archived   Include archived projects (default: active only)
+ *   --format <fmt>       Output format: table (default), csv, or json
+ */
+
+import { createScript, defineMeta } from '@studiometa/productive-cli/script';
+
+export const meta = defineMeta({
+  name: 'Project List',
+  description: 'List active projects with optional search and format.',
+  usage: '[--search <term>] [--include-archived] [--format table|csv|json]',
+});
+
+export default createScript(async ({ client, output, flags }) => {
+  const search = flags.search as string | undefined;
+  const includeArchived = flags['include-archived'] === true;
+  const format = (flags.format as string | undefined) ?? 'table';
+
+  const filter: Record<string, string> = {};
+  if (!includeArchived) filter.status = 'active';
+
+  const projects = await output.spinner('Fetching projects…', () =>
+    client.projects.all({ filter }).toArray(),
+  );
+
+  const matched = search
+    ? projects.filter((p) => p.name.toLowerCase().includes(search.toLowerCase()))
+    : projects;
+
+  if (matched.length === 0) {
+    output.info(search ? `No projects matching "${search}".` : 'No projects found.');
+    return;
+  }
+
+  const rows = matched.map((p) => ({
+    id: p.id,
+    number: p.project_number ?? '—',
+    name: p.name,
+    archived: p.archived ? 'yes' : 'no',
+  }));
+
+  if (format === 'csv') {
+    output.csv(rows);
+  } else if (format === 'json') {
+    output.json(rows);
+  } else {
+    output.table(rows);
+    output.info(`${matched.length} project${matched.length === 1 ? '' : 's'} found`);
+  }
+});
@@ -0,0 +1,71 @@
+/**
+ * Export time entries for a date range.
+ *
+ * Usage:
+ *   productive run examples/time-report.ts --from 2025-01-01 --to 2025-01-31
+ *   productive run examples/time-report.ts --from 2025-01-01 --to 2025-01-31 --format csv
+ *   productive run examples/time-report.ts --from 2025-01-01 --to 2025-01-31 --mine
+ *
+ * Flags:
+ *   --from <date>    Start date (YYYY-MM-DD), required
+ *   --to <date>      End date (YYYY-MM-DD), required
+ *   --mine           Filter to your own entries only (default: all team entries)
+ *   --format <fmt>   Output format: table (default), csv, or json
+ */
+
+import { createScript, defineMeta } from '@studiometa/productive-cli/script';
+
+export const meta = defineMeta({
+  name: 'Time Report',
+  description: 'Export time entries for a date range.',
+  usage: '--from <YYYY-MM-DD> --to <YYYY-MM-DD> [--mine] [--format table|csv|json]',
+});
+
+export default createScript(async ({ client, output, flags }) => {
+  const from = flags.from as string | undefined;
+  const to = flags.to as string | undefined;
+  const format = (flags.format as string | undefined) ?? 'table';
+
+  if (!from || !to) {
+    output.error('--from and --to are required. Example: --from 2025-01-01 --to 2025-01-31');
+    process.exit(1);
+  }
+
+  const filter: Record<string, string> = {
+    after: from,
+    before: to,
+  };
+
+  if (flags.mine) {
+    filter.person_id = process.env.PRODUCTIVE_USER_ID ?? '';
+  }
+
+  const entries = await output.spinner(`Fetching time entries from ${from} to ${to}…`, () =>
+    client.time.all({ filter }).toArray(),
+  );
+
+  if (entries.length === 0) {
+    output.info('No time entries found for the selected period.');
+    return;
+  }
+
+  // Productive stores time in minutes — convert to decimal hours for readability
+  const rows = entries.map((e) => ({
+    id: e.id,
+    date: e.date,
+    hours: (e.time / 60).toFixed(2),
+    note: e.note ?? '',
+  }));
+
+  const totalMinutes = entries.reduce((sum, e) => sum + e.time, 0);
+  const totalHours = (totalMinutes / 60).toFixed(2);
+
+  if (format === 'csv') {
+    output.csv(rows);
+  } else if (format === 'json') {
+    output.json(rows);
+  } else {
+    output.table(rows);
+    output.info(`Total: ${totalHours}h across ${entries.length} entries`);
+  }
+});
@@ -31,6 +31,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./script": {
+      "types": "./dist/script.d.ts",
+      "import": "./dist/script.js"
     }
   },
   "publishConfig": {
@@ -45,7 +49,8 @@
   },
   "dependencies": {
     "@studiometa/productive-api": "*",
-    "@studiometa/productive-core": "*"
+    "@studiometa/productive-core": "*",
+    "@studiometa/productive-sdk": "*"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.0-beta.5",