ttctl 0.0.0 → 0.1.0-rc.1

package/README.md

@@ -1,27 +1,60 @@
 # ttctl
 
-> **Placeholder reservation.** The real release is in development.
+[![npm](https://img.shields.io/npm/v/ttctl?logo=npm)](https://www.npmjs.com/package/ttctl)
+[![License](https://img.shields.io/npm/l/ttctl)](https://github.com/alexey-pelykh/ttctl/blob/main/LICENSE)
 
-This package on npm is currently a **name reservation**. There is no working CLI, MCP server, or library here yet — only a stub that exists to hold the `ttctl` name on the npm registry while the real implementation is finalized.
+Unofficial CLI and MCP server for [Toptal Talent](https://talent.toptal.com) — your own profile, your own session, your own data.
 
-## What this will become
+> **Unofficial.** TTCtl is NOT affiliated with, endorsed by, or supported by Toptal LLC. See the [project README](https://github.com/alexey-pelykh/ttctl#readme) for the full use policy and disclaimer.
 
-`ttctl` is the unofficial personal-productivity CLI and MCP server for [Toptal Talent](https://talent.toptal.com) profiles — built for fair use against your **own** profile only.
+## Install
 
-For the real status of development, the source code, the architecture, and the unofficial-tool guardrails, see:
+```sh
+npm install -g ttctl
+```
 
-**→ https://github.com/alexey-pelykh/ttctl**
+Or run directly with npx:
 
-The real first release will replace this placeholder shortly. If you installed this package looking for a working tool, please uninstall it and watch the GitHub repository for the real release announcement.
+```sh
+npx ttctl --help
+```
 
-## ⚠️ Unofficial — Personal Use Only
+Requires **Node.js ≥ 24**.
 
-`ttctl` is **NOT** affiliated with, endorsed by, or supported by Toptal LLC. It is a personal-productivity tool that interacts with Toptal Talent's interfaces using your own session, exclusively for your own profile's data.
+## What's in this package
 
-It is **NOT** to be used for spam, mass automation, recruiter scraping, engagement-signal manipulation, or operating against profiles that aren't your own. See the [GitHub repository](https://github.com/alexey-pelykh/ttctl) for the full unofficial-tool policy.
+`ttctl` is the **umbrella binary**. It bundles two sibling packages so end users get one install:
 
-"Toptal" is a trademark of Toptal LLC. The name appears here as **nominative fair use** only — `ttctl` is not a Toptal brand.
+- [`@ttctl/cli`](https://www.npmjs.com/package/@ttctl/cli) — the Commander program (`ttctl profile show`, `ttctl timesheet list`, `ttctl auth signin`, …)
+- [`@ttctl/mcp`](https://www.npmjs.com/package/@ttctl/mcp) — the MCP server (`ttctl mcp` on stdio)
+
+If you only need part of TTCtl in another program, install the sibling package directly. For interactive use, this umbrella is the package you want.
+
+## Quick Start
+
+```sh
+# 1. Bootstrap config interactively (Form A: 1Password reference, recommended)
+ttctl auth init
+
+# 2. Sign in — captures the bearer back into ~/.ttctl.yaml
+ttctl auth signin
+
+# 3. Verify
+ttctl auth status
+
+# 4. View your profile
+ttctl profile show
+```
+
+## MCP
+
+```sh
+# Start the MCP server on stdio (typically spawned by your MCP client)
+ttctl mcp
+```
+
+For Claude Desktop / Claude Code / Cursor configuration snippets, the full sub-command reference, configuration shapes (Forms A–D, sync-root exclusions, debug instrumentation), and the disclaimer / fair-use posture, see the [**project README**](https://github.com/alexey-pelykh/ttctl#readme).
 
 ## License
 
-[AGPL-3.0-only](./LICENSE)
+[AGPL-3.0-only](https://github.com/alexey-pelykh/ttctl/blob/main/LICENSE). Using the `ttctl` binary as a tool does not impose AGPL obligations on your own code; importing the constituent libraries (`@ttctl/cli` / `@ttctl/mcp` / `@ttctl/core`) does. See the project README's [License](https://github.com/alexey-pelykh/ttctl#license) section.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+import { ConfigError, TtctlError, buildProgram, installCrashHandlers, presentTtctlError } from "@ttctl/cli";
+import { runMcpStdio } from "@ttctl/mcp";
+// Wire `uncaughtException` and `unhandledRejection` handlers BEFORE any other
+// executable code (issue #207). The `main().catch()` below covers anything
+// that flows through the awaited Promise chain; the global handlers cover
+// what escapes — fire-and-forget Promise rejections in tool callbacks,
+// throws from `setTimeout` / `setImmediate` / `process.nextTick` callbacks,
+// EventEmitter listeners not in `main`'s chain. Both paths redact captured
+// Toptal session bearers via `redactString` from `@ttctl/core`.
+installCrashHandlers();
+/**
+ * Umbrella entrypoint: dispatches to MCP-server mode if invoked as
+ * `ttctl mcp`, otherwise routes to the Commander CLI program.
+ *
+ * The MCP branch is kept first so its early dispatch doesn't conflict with
+ * commander's argv parsing.
+ *
+ * MCP `--config <path>` (#113): the umbrella parses the flag from argv
+ * after the `mcp` subcommand position and threads it into
+ * `runMcpStdio({ configPath })`. The path is captured ONCE inside
+ * `buildServer`; subsequent tool invocations read/write the same path
+ * regardless of mid-session env-var changes. Startup-time
+ * `resolveConfig(NO_CREDS)` propagates as a non-zero exit so the MCP
+ * client sees a clean failure rather than a half-initialized server.
+ */
+async function main() {
+    if (process.argv[2] === "mcp") {
+        const configPath = parseConfigFlag(process.argv.slice(3));
+        try {
+            await runMcpStdio(configPath !== undefined ? { configPath } : {});
+        }
+        catch (err) {
+            if (err instanceof ConfigError) {
+                process.stderr.write(`Error (${err.code}): ${err.message}\n`);
+                process.exit(1);
+            }
+            throw err;
+        }
+        return;
+    }
+    const program = buildProgram();
+    await program.parseAsync(process.argv);
+}
+/**
+ * Parse `--config <path>` (and `--config=<path>`) from a flat argv slice.
+ * Returns the first match or `undefined`. Unknown flags are ignored —
+ * the MCP server has no other entry-flags today, but this keeps the
+ * function tolerant for future additions (SSE port, transport selector,
+ * …) layered on top by sister tools.
+ */
+function parseConfigFlag(args) {
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--config") {
+            return args[i + 1];
+        }
+        if (arg !== undefined && arg.startsWith("--config=")) {
+            return arg.slice("--config=".length);
+        }
+    }
+    return undefined;
+}
+main().catch((err) => {
+    // Top-level safety net: any TtctlError that escapes a command handler is
+    // rendered in the uniform Error/Recovery/Code format (issue #77). Other
+    // unexpected errors fall through to the generic single-line stderr.
+    if (err instanceof TtctlError)
+        presentTtctlError(err);
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC5G,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,8EAA8E;AAC9E,2EAA2E;AAC3E,0EAA0E;AAC1E,uEAAuE;AACvE,4EAA4E;AAC5E,2EAA2E;AAC3E,gEAAgE;AAChE,oBAAoB,EAAE,CAAC;AAEvB;;;;;;;;;;;;;;GAcG;AACH,KAAK,UAAU,IAAI;IACjB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC;QAC9B,MAAM,UAAU,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1D,IAAI,CAAC;YACH,MAAM,WAAW,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACpE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,WAAW,EAAE,CAAC;gBAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;gBAC9D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,OAAO;IACT,CAAC;IAED,MAAM,OAAO,GAAG,YAAY,EAAE,CAAC;IAC/B,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,IAAuB;IAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACrB,CAAC;QACD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YACrD,OAAO,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,yEAAyE;IACzE,wEAAwE;IACxE,oEAAoE;IACpE,IAAI,GAAG,YAAY,UAAU;QAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACtD,OAAO,CAAC,KAAK,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { buildProgram } from "@ttctl/cli";
+export { buildServer, runMcpStdio } from "@ttctl/mcp";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (C) 2026 Oleksii PELYKH
+export { buildProgram } from "@ttctl/cli";
+export { buildServer, runMcpStdio } from "@ttctl/mcp";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,oCAAoC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "ttctl",
-  "version": "0.0.0",
-  "description": "Unofficial CLI and MCP server for the Toptal Talent platform — placeholder reservation; real release in development",
+  "version": "0.1.0-rc.1",
+  "description": "Unofficial CLI and MCP server for the Toptal Talent platform",
   "type": "module",
-  "main": "./index.js",
+  "engines": {
+    "node": ">=22.19.0"
+  },
   "license": "AGPL-3.0-only",
   "author": "Alexey Pelykh (https://github.com/alexey-pelykh)",
   "homepage": "https://github.com/alexey-pelykh/ttctl",
@@ -11,17 +13,46 @@
   "funding": "https://github.com/sponsors/alexey-pelykh",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/alexey-pelykh/ttctl.git"
+    "url": "https://github.com/alexey-pelykh/ttctl.git",
+    "directory": "packages/ttctl"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    }
   },
+  "bin": {
+    "ttctl": "./dist/cli.js"
+  },
+  "mcpName": "io.github.alexey-pelykh/ttctl",
   "keywords": [
     "toptal-talent",
     "mcp",
-    "cli",
-    "placeholder"
+    "cli"
   ],
   "files": [
-    "index.js",
-    "README.md",
-    "LICENSE"
-  ]
-}
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ttctl/cli": "^0.1.0-rc.1",
+    "@ttctl/mcp": "^0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25",
+    "eslint": "^10.3.0",
+    "typescript": "~6.0.3",
+    "vitest": "^4.1.1"
+  },
+  "scripts": {
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "lint": "eslint src/",
+    "dev": "tsc --watch"
+  }
+}

package/index.js

@@ -1,7 +0,0 @@
-// ttctl placeholder — name reservation only.
-// The real release is in development at https://github.com/alexey-pelykh/ttctl
-console.log(
-  "ttctl: this is a placeholder reservation, not a functional release.\n" +
-    "The real CLI / MCP server is in development. See:\n" +
-    "  https://github.com/alexey-pelykh/ttctl",
-);