@locusai/sdk 0.25.0 → 0.25.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +151 -0
  2. package/package.json +1 -1
package/README.md ADDED
@@ -0,0 +1,151 @@
1
+ # @locusai/sdk
2
+
3
+ [![npm version](https://img.shields.io/npm/v/@locusai/sdk?color=blue)](https://www.npmjs.com/package/@locusai/sdk)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/asgarovf/locusai/blob/master/LICENSE)
5
+
6
+ SDK for building [Locus](https://github.com/asgarovf/locusai)-compatible community packages. Provides configuration management, CLI invocation, structured logging, and TypeScript type definitions.
7
+
8
+ ## Installation
9
+
10
+ ```bash
11
+ npm install @locusai/sdk
12
+ ```
13
+
14
+ ## Quick Start
15
+
16
+ ```ts
17
+ import {
18
+ readLocusConfig,
19
+ invokeLocus,
20
+ invokeLocusStream,
21
+ createLogger,
22
+ } from "@locusai/sdk";
23
+
24
+ // Read merged project + global config
25
+ const config = readLocusConfig();
26
+
27
+ // Run a Locus CLI command and capture output
28
+ const result = await invokeLocus(["status"]);
29
+ console.log(result.stdout);
30
+
31
+ // Stream output from a long-running command
32
+ const child = invokeLocusStream(["run", "42"]);
33
+ child.stdout?.pipe(process.stdout);
34
+
35
+ // Create a logger for your package
36
+ const log = createLogger("my-package");
37
+ log.info("Package initialized");
38
+ ```
39
+
40
+ ## API Reference
41
+
42
+ ### Configuration
43
+
44
+ #### `readLocusConfig(cwd?: string): LocusConfig`
45
+
46
+ Reads and merges global (`~/.locus/config.json`) and project-level (`.locus/config.json`) configuration files. Project config takes precedence over global config.
47
+
48
+ ```ts
49
+ import { readLocusConfig } from "@locusai/sdk";
50
+
51
+ const config = readLocusConfig();
52
+ console.log(config.ai.model); // configured AI model
53
+ console.log(config.packages?.telegram); // package-specific config
54
+ ```
55
+
56
+ #### `DEFAULT_CONFIG`
57
+
58
+ Safe defaults for all configuration sections. Useful as a fallback.
59
+
60
+ ### Invocation
61
+
62
+ #### `invokeLocus(args: string[], cwd?: string): Promise<LocusInvokeResult>`
63
+
64
+ Spawns the `locus` CLI binary and captures output. Returns stdout, stderr, and exit code.
65
+
66
+ ```ts
67
+ import { invokeLocus } from "@locusai/sdk";
68
+
69
+ const result = await invokeLocus(["exec", "--non-interactive", "explain this code"]);
70
+ console.log(result.stdout); // AI response
71
+ console.log(result.exitCode); // 0 on success
72
+ ```
73
+
74
+ #### `invokeLocusStream(args: string[], cwd?: string): ChildProcess`
75
+
76
+ Returns a raw `ChildProcess` for streaming output. Use this for long-running commands where you need real-time output.
77
+
78
+ ```ts
79
+ import { invokeLocusStream } from "@locusai/sdk";
80
+
81
+ const child = invokeLocusStream(["run", "42"]);
82
+ child.stdout?.on("data", (chunk) => process.stdout.write(chunk));
83
+ child.on("close", (code) => console.log("Exit:", code));
84
+ ```
85
+
86
+ ### Logging
87
+
88
+ #### `createLogger(name: string): LocusLogger`
89
+
90
+ Creates a named logger with consistent formatting matching Locus CLI output. All output goes to stderr to avoid polluting stdout.
91
+
92
+ ```ts
93
+ import { createLogger } from "@locusai/sdk";
94
+
95
+ const log = createLogger("my-package");
96
+ log.info("Started"); // ● [my-package] Started
97
+ log.warn("Rate limited"); // ⚠ [my-package] Rate limited
98
+ log.error("Connection lost"); // ✗ [my-package] Connection lost
99
+ log.debug("Payload:", data); // ⋯ [my-package] Payload: ... (only with LOCUS_DEBUG=1)
100
+ ```
101
+
102
+ ### Types
103
+
104
+ ```ts
105
+ import type {
106
+ LocusConfig,
107
+ LocusPackageManifest,
108
+ LocusInvokeResult,
109
+ LocusLogger,
110
+ AIProvider,
111
+ } from "@locusai/sdk";
112
+ ```
113
+
114
+ | Type | Description |
115
+ |------|-------------|
116
+ | `LocusConfig` | Full configuration schema (AI, GitHub, agent, sprint, sandbox, packages) |
117
+ | `LocusPackageManifest` | Shape of the `"locus"` field in package.json |
118
+ | `LocusInvokeResult` | Return type from `invokeLocus()` — `{ stdout, stderr, exitCode }` |
119
+ | `LocusLogger` | Logger interface with `info`, `warn`, `error`, `debug` methods |
120
+ | `AIProvider` | Union type: `"claude" | "codex"` |
121
+
122
+ ## Building a Package
123
+
124
+ See the [Package Author Guide](./PACKAGE_GUIDE.md) for a complete walkthrough covering:
125
+
126
+ - Package structure and naming conventions (`@locusai/locus-<name>`)
127
+ - Required `package.json` fields and the `"locus"` manifest
128
+ - Using the SDK for config, invocation, and logging
129
+ - Building, testing, and publishing
130
+ - Submitting a pull request
131
+
132
+ You can also scaffold a new package with:
133
+
134
+ ```bash
135
+ locus create my-package
136
+ ```
137
+
138
+ ## Related Packages
139
+
140
+ | Package | Description |
141
+ |---------|-------------|
142
+ | [`@locusai/cli`](../cli) | Main Locus CLI |
143
+ | [`@locusai/locus-gateway`](../gateway) | Channel-agnostic message gateway for platform adapters |
144
+ | [`@locusai/locus-pm2`](../pm2) | PM2 process management for background workers |
145
+ | [`@locusai/locus-telegram`](../telegram) | Telegram adapter — reference implementation |
146
+ | [`@locusai/locus-cron`](../cron) | Cron scheduler package |
147
+ | [`@locusai/locus-linear`](../linear) | Linear integration package |
148
+
149
+ ## License
150
+
151
+ [MIT](https://github.com/asgarovf/locusai/blob/master/LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@locusai/sdk",
3
- "version": "0.25.0",
3
+ "version": "0.25.2",
4
4
  "description": "SDK for building Locus-compatible community packages",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",