@locusai/sdk 0.21.13 → 0.21.14

package/PACKAGE_GUIDE.md

@@ -1,84 +1,167 @@
 # Locus Package Author Guide
 
-This guide explains how to build, test, and publish a community package for
-the [Locus](https://github.com/locusai/locus) CLI.
+This guide explains how to build, test, and contribute a community package to
+the [Locus](https://github.com/asgarovf/locusai) monorepo.
+
+All community packages live inside the Locus repository under `packages/` and
+are published to npm through the project's automated release pipeline.
+To add a new package, you prepare it in the repo and submit a pull request.
+
+---
+
+## How packages work
+
+When a user runs `locus install <name>`, the CLI fetches the package from npm
+and places it in `~/.locus/packages/`. The user then invokes it via
+`locus pkg <name> [args...]`, which resolves the binary and forwards arguments.
+
+Packages use the `@locusai/sdk` to read project config, invoke Locus
+sub-commands, and log with consistent formatting.
 
 ---
 
 ## Naming convention
 
-All Locus packages must be published to npm with the prefix `locus-`:
+All official Locus packages are scoped under `@locusai` and prefixed with
+`locus-`:
+
+| Short name | npm package name             |
+|------------|------------------------------|
+| `telegram` | `@locusai/locus-telegram`    |
+| `slack`    | `@locusai/locus-slack`       |
+| `jira`     | `@locusai/locus-jira`        |
+
+Users install packages by short name:
 
-| Short name | npm package name  |
-|------------|-------------------|
-| `telegram` | `locus-telegram`  |
-| `slack`    | `locus-slack`     |
-| `jira`     | `locus-jira`      |
+```sh
+locus install telegram        # resolves to @locusai/locus-telegram
+locus install slack           # resolves to @locusai/locus-slack
+```
 
-Scoped packages (e.g. `@myorg/locus-telegram`) are also accepted and will be
-used as-is.
+---
+
+## Package structure
+
+Every package lives in `packages/<name>/` inside the monorepo. Use the
+`@locusai/locus-telegram` package as the canonical reference.
+
+```
+packages/<name>/
+├── bin/
+│   └── locus-<name>.js       # Compiled binary (build output)
+├── src/
+│   ├── cli.ts                 # Entry point (delegates to index.ts)
+│   └── index.ts               # Main logic
+├── package.json
+├── tsconfig.json
+└── README.md
+```
 
 ---
 
-## `package.json` manifest format
+## `package.json` requirements
 
-Every Locus package **must** include a `"locus"` field in its `package.json`.
-This field tells the Locus CLI how to display and invoke your package.
+Every package **must** include these fields:
 
 ```jsonc
 {
-  "name": "locus-telegram",
-  "version": "1.0.0",
-  "description": "Remote-control Locus via Telegram",
+  "name": "@locusai/locus-<name>",
+  "version": "0.21.13",
+  "description": "Short description of what the package does",
+  "type": "module",
   "bin": {
-    "locus-telegram": "./bin/locus-telegram.js"
+    "locus-<name>": "./bin/locus-<name>.js"
   },
+  "files": [
+    "bin",
+    "package.json",
+    "README.md"
+  ],
 
   // Required: Locus package manifest
   "locus": {
-    "displayName": "Telegram",
-    "description": "Remote-control your Locus agent from Telegram",
-    "commands": ["telegram"],
-    "version": "1.0.0"
-  }
+    "displayName": "Human Name",
+    "description": "One-line description shown in locus packages list",
+    "commands": ["<name>"],
+    "version": "0.1.0"
+  },
+
+  "scripts": {
+    "build": "bun build src/cli.ts --outfile bin/locus-<name>.js --target node",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint .",
+    "format": "biome format --write ."
+  },
+
+  "dependencies": {
+    "@locusai/sdk": "^0.21.13"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "keywords": [
+    "locusai-package",
+    "locus"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
 }
 ```
 
-| Field         | Type       | Description                                                      |
-|---------------|------------|------------------------------------------------------------------|
-| `displayName` | `string`   | Human-readable name shown in `locus packages list`.             |
-| `description` | `string`   | One-line description shown in `locus packages list`.            |
-| `commands`    | `string[]` | Sub-commands contributed. Used in `locus pkg <name>` dispatch.  |
-| `version`     | `string`   | Semver version — should mirror the npm package version.         |
+### Required fields explained
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Must be `@locusai/locus-<name>`. |
+| `bin` | `object` | Binary entry point. Key must be `locus-<name>`. |
+| `files` | `string[]` | Must include `"bin"`, `"package.json"`, `"README.md"`. Without this, npm may not ship compiled code. |
+| `keywords` | `string[]` | **Must** include `"locusai-package"`. This is how the [packages page](https://locusai.dev/packages) discovers your package on npm. Without it, your package won't appear in the marketplace. |
+| `locus.displayName` | `string` | Human-readable name shown in `locus packages list`. |
+| `locus.description` | `string` | One-line description for the package listing. |
+| `locus.commands` | `string[]` | Sub-commands contributed. Used in `locus pkg <name>` dispatch. |
+| `locus.version` | `string` | Semver version for the Locus integration. |
+| `engines` | `object` | Must require Node.js 18+. |
+
+### Important: dependency versions
+
+Never use `workspace:*` for dependencies that get published to npm. Use real
+semver versions (e.g., `"^0.21.13"`) for inter-package deps like `@locusai/sdk`.
+The `workspace:` protocol is not resolved by `npm publish`.
 
 ---
 
 ## Binary entry point
 
-Your package must expose a binary. Locus discovers it via
-`~/.locus/packages/node_modules/.bin/locus-<name>` after installation.
+Your package must expose a binary via the `"bin"` field. After installation, Locus
+discovers it at `~/.locus/packages/node_modules/.bin/locus-<name>`.
 
-In `package.json`:
+The binary should be a compiled JavaScript file with a shebang:
 
-```json
-"bin": {
-  "locus-telegram": "./bin/locus-telegram.js"
-}
-```
+```js
+#!/usr/bin/env node
+import { main } from "./index.js";
 
-The binary should be executable Node.js (shebang `#!/usr/bin/env node`).
+main(process.argv.slice(2)).catch((error) => {
+  console.error(`Fatal error: ${error.message}`);
+  process.exit(1);
+});
+```
 
-When invoked via `locus pkg telegram [args...]`, the remaining args are
-forwarded to your binary verbatim.
+When invoked via `locus pkg <name> [args...]`, the remaining args are forwarded
+to your binary verbatim.
 
 ---
 
 ## Using `@locusai/sdk`
 
-Install the SDK as a dev dependency (it is a peer contract, not bundled):
+Add the SDK as a dependency (use a real semver version, not `workspace:*`):
 
-```sh
-npm install --save-dev @locusai/sdk
+```json
+"dependencies": {
+  "@locusai/sdk": "^0.21.13"
+}
 ```
 
 ### Reading project config
@@ -115,155 +198,161 @@ child.on("exit", (code) => console.log("exited with", code));
 ```ts
 import { createLogger } from "@locusai/sdk";
 
-const logger = createLogger("telegram");
+const logger = createLogger("mypackage");
 
-logger.info("Bot started");
+logger.info("Started");
 logger.warn("Rate limit approaching", { remaining: 5 });
 logger.error("Connection failed", { code: 503 });
-logger.debug("Raw update", { update_id: 12345 }); // only shown with LOCUS_DEBUG=1
+logger.debug("Debug info", { detail: "value" }); // only shown with LOCUS_DEBUG=1
 ```
 
 Output uses the same prefix symbols as the Locus CLI (`●`, `⚠`, `✗`, `⋯`).
 
 ---
 
-## Minimal end-to-end example
+## Step-by-step: adding a new package
 
-Below is a complete minimal Locus package (`locus-hello`).
+### 1. Create the package directory
 
-### Directory structure
-
-```
-locus-hello/
-├── bin/
-│   └── locus-hello.js
-├── src/
-│   └── index.ts
-├── package.json
-└── tsconfig.json
+```sh
+mkdir -p packages/<name>/src packages/<name>/bin
 ```
 
-### `package.json`
+### 2. Create `package.json`
+
+Use the template above. Set the `name` to `@locusai/locus-<name>` and fill in
+the `locus` manifest.
+
+### 3. Create `tsconfig.json`
 
 ```json
 {
-  "name": "locus-hello",
-  "version": "1.0.0",
-  "description": "Example Locus package",
-  "type": "module",
-  "bin": {
-    "locus-hello": "./bin/locus-hello.js"
-  },
-  "locus": {
-    "displayName": "Hello",
-    "description": "A minimal example Locus package",
-    "commands": ["hello"],
-    "version": "1.0.0"
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./bin",
+    "rootDir": "./src"
   },
-  "scripts": {
-    "build": "tsc"
-  },
-  "devDependencies": {
-    "@locusai/sdk": "^0.1.0",
-    "typescript": "^5.0.0"
-  }
+  "include": ["src"]
 }
 ```
 
-### `src/index.ts`
+### 4. Write your source code
+
+Create `src/cli.ts` as the entry point:
+
+```ts
+import { main } from "./index.js";
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(`Fatal error: ${error.message}`);
+  process.exit(1);
+});
+```
+
+Create `src/index.ts` with your main logic:
 
 ```ts
 import { createLogger, readLocusConfig } from "@locusai/sdk";
 
-const logger = createLogger("hello");
+const logger = createLogger("<name>");
 
-export async function run(): Promise<void> {
+export async function main(args: string[]): Promise<void> {
   const config = readLocusConfig();
-  logger.info(`Hello from locus-hello! Repo: ${config.github.owner}/${config.github.repo}`);
+  logger.info(`Hello from locus-<name>! Repo: ${config.github.owner}/${config.github.repo}`);
+  // Your logic here
 }
 ```
 
-### `bin/locus-hello.js`
+### 5. Add build script to root `package.json`
 
-```js
-#!/usr/bin/env node
-import "../dist/index.js";
+Add your package's build to the root `build:packages` script:
 
-const { run } = await import("../dist/index.js");
-await run();
+```json
+"build:<name>": "cd packages/<name> && bun run build"
 ```
 
-Make it executable:
+And include it in the `build:packages` chain.
 
-```sh
-chmod +x bin/locus-hello.js
-```
+### 6. Build and test locally
 
----
-
-## Testing locally with `npm link`
+```sh
+# Install dependencies
+bun install
 
-1. Build your package:
+# Build your package
+cd packages/<name> && bun run build
 
-   ```sh
-   npm run build
-   ```
+# Test it locally via symlink
+mkdir -p ~/.locus/packages/node_modules/.bin
+ln -s $(pwd)/bin/locus-<name>.js ~/.locus/packages/node_modules/.bin/locus-<name>
+mkdir -p ~/.locus/packages/node_modules/@locusai/locus-<name>
+ln -s $(pwd)/package.json ~/.locus/packages/node_modules/@locusai/locus-<name>/package.json
+ln -s $(pwd)/bin ~/.locus/packages/node_modules/@locusai/locus-<name>/bin
 
-2. Link it globally:
+# Run your package
+locus pkg <name>
+```
 
-   ```sh
-   npm link
-   ```
+### 7. Write a README
 
-3. Install it into Locus's packages directory:
+Every package must have a `README.md` that explains:
+- What the package does
+- Setup and configuration steps
+- Available commands and usage
+- Any required environment variables or API keys
 
-   ```sh
-   locus install locus-hello
-   ```
+See `packages/telegram/README.md` for a complete example.
 
-   Or, for a faster dev loop, symlink directly:
+### 8. Submit a pull request
 
-   ```sh
-   mkdir -p ~/.locus/packages/node_modules
-   ln -s $(pwd) ~/.locus/packages/node_modules/locus-hello
-   mkdir -p ~/.locus/packages/node_modules/.bin
-   ln -s $(pwd)/bin/locus-hello.js ~/.locus/packages/node_modules/.bin/locus-hello
-   ```
+Once your package builds, typechecks, and works locally:
 
-4. Run your package:
+1. Fork the [Locus repository](https://github.com/asgarovf/locusai)
+2. Create a feature branch: `git checkout -b feat/locus-<name>`
+3. Add a changeset: `bun changeset` (select your new package, choose `minor`)
+4. Commit your changes and push
+5. Open a pull request against `master`
 
-   ```sh
-   locus pkg hello
-   ```
+The maintainers will review your package. Once merged, it will be published to
+npm automatically through the Changesets release pipeline.
 
 ---
 
-## Publishing to npm
+## Reference: `@locusai/locus-telegram`
 
-1. Make sure the `"locus"` field is present in your `package.json`.
-2. Ensure the binary listed in `"bin"` is executable.
-3. Build your package.
-4. Publish:
+The Telegram package (`packages/telegram/`) is the canonical example of a
+community package. Study its structure for:
 
-   ```sh
-   npm publish --access public
-   ```
+- **`package.json`**: Correct naming, `locus` manifest, `files` field, dependency versions
+- **`src/cli.ts`**: Entry point pattern (delegates to `index.ts`)
+- **`src/index.ts`**: Main logic using the SDK
+- **Build script**: Uses `bun build` to compile to a single binary
+- **README.md**: Complete documentation with setup, usage, and configuration
 
-After publishing, users can install your package with:
+---
 
-```sh
-locus install hello     # short name (locus-hello)
-locus install locus-hello
-```
+## Tooling and conventions
 
----
+- **Package manager**: [Bun](https://bun.sh) (the monorepo uses `bun@1.2.4`)
+- **Bundler**: `bun build` (compiles TypeScript to a single Node.js binary)
+- **Linter**: [Biome](https://biomejs.dev/) — run `bun run lint` and `bun run format`
+- **TypeScript**: 5.8+ — run `bun run typecheck`
+- **Releases**: [Changesets](https://github.com/changesets/changesets) — automated via GitHub Actions
 
-## Checklist before publishing
+---
 
-- [ ] Package name starts with `locus-` (or is scoped)
-- [ ] `"locus"` field present in `package.json` with all required keys
-- [ ] Binary listed in `"bin"` exists and has the shebang line
-- [ ] Binary is executable (`chmod +x`)
-- [ ] Package builds cleanly with no TypeScript errors
+## Checklist before submitting your PR
+
+- [ ] Package lives in `packages/<name>/` in the monorepo
+- [ ] `package.json` name is `@locusai/locus-<name>`
+- [ ] `"locus"` field present with all required keys (`displayName`, `description`, `commands`, `version`)
+- [ ] `"files"` field includes `"bin"`, `"package.json"`, `"README.md"`
+- [ ] `"keywords"` includes `"locusai-package"` (required for marketplace discovery)
+- [ ] `"bin"` field points to `./bin/locus-<name>.js`
+- [ ] Dependencies use real semver versions (no `workspace:*`)
+- [ ] Binary builds cleanly with `bun run build`
+- [ ] `bun run typecheck` passes with no errors
+- [ ] `bun run lint` passes with no errors
 - [ ] Tested locally with `locus pkg <name>`
-- [ ] `README.md` explains what the package does and how to configure it
+- [ ] `README.md` explains setup, configuration, and usage
+- [ ] Changeset added via `bun changeset`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@locusai/sdk",
-  "version": "0.21.13",
+  "version": "0.21.14",
   "description": "SDK for building Locus-compatible community packages",
   "type": "module",
   "main": "./dist/index.cjs",