@secondlayer/cli 3.1.0 → 3.1.2-alpha.0

package/README.md

@@ -0,0 +1,204 @@
+# @secondlayer/cli
+
+The Secondlayer CLI — one binary for dedicated Stacks indexing, real-time
+subgraphs, and per-tenant hosting lifecycle.
+
+```bash
+bun add -g @secondlayer/cli
+sl --version
+```
+
+## Quickstart
+
+```bash
+sl login                         # magic-link auth, session cached at ~/.secondlayer/session.json
+sl project create my-app         # scaffold a project
+sl project use my-app            # bind cwd to the project (writes ./.secondlayer/project)
+sl instance create --plan launch # provision dedicated Postgres + API + processor
+sl subgraphs deploy ./x.ts       # deploy to your instance
+```
+
+## Command surface
+
+### Auth (top-level)
+
+| Command | What it does |
+|---|---|
+| `sl login` | Magic-link email → 6-digit code → writes session to `~/.secondlayer/session.json` |
+| `sl logout` | Revokes the session and clears the local file |
+| `sl whoami` | Prints account, active project, instance URL, plan, status |
+
+### Project
+
+Projects are the unit that binds a working directory to a dedicated instance.
+Binding is **per-directory** — `.secondlayer/project` in cwd takes precedence
+over the global default at `~/.secondlayer/config.json:defaultProject`. The
+walk-up stops at `.git` (never crosses repos).
+
+| Command | What it does |
+|---|---|
+| `sl project create [name]` | Scaffold a new project on the platform |
+| `sl project list` | List all projects for the account |
+| `sl project use <slug>` | Write `./.secondlayer/project` — binds cwd to that project |
+| `sl project current` | Prints the resolved slug + the file it was read from |
+
+### Instance (dedicated hosting)
+
+One instance per project. The platform API spawns a dedicated `sl-pg-{slug}`,
+`sl-api-{slug}`, and `sl-proc-{slug}` container set on the hosting side.
+
+| Command | What it does |
+|---|---|
+| `sl instance create --plan <launch\|grow\|scale>` | Provision containers. Boxed reveal of `serviceKey` + `anonKey` (shown once). |
+| `sl instance info` | Plan, status, resource usage |
+| `sl instance resize --plan <...>` | Recreate containers with new CPU/memory (~30s downtime) |
+| `sl instance suspend` / `resume` | Stop/start containers, volume preserved |
+| `sl instance keys rotate [--service\|--anon\|--both]` | Bump JWT gen, recreate API container, mint replacement key(s) |
+| `sl instance delete` | Typed-slug confirm, hard teardown |
+| `sl instance db` | Print `ssh -L` command + `DATABASE_URL` for tunneled Postgres access |
+| `sl instance db add-key <path>` | Upload an SSH pubkey to the bastion |
+| `sl instance db revoke-key` | Revoke your bastion access |
+
+### Subgraphs (tenant-scoped)
+
+All tenant-scoped commands auto-mint a 5-minute ephemeral service JWT per
+invocation. No long-lived key on disk.
+
+| Command | What it does |
+|---|---|
+| `sl subgraphs new <name>` | Scaffold a subgraph definition file |
+| `sl subgraphs deploy <file>` | Deploy to the active instance |
+| `sl subgraphs dev <file>` | Watch + hot-redeploy |
+| `sl subgraphs list` | List deployed subgraphs |
+| `sl subgraphs status <name>` | Indexing progress, row counts, gaps |
+| `sl subgraphs query <name> <table>` | Query a subgraph table with filters, sort, pagination |
+| `sl subgraphs reindex <name>` | Drop + re-process from the tip backwards |
+| `sl subgraphs backfill <name>` | Fill a specific block range |
+| `sl subgraphs stop <name>` | Pause processing |
+| `sl subgraphs gaps <name>` | List missing block ranges |
+| `sl subgraphs delete <name>` | Drop the subgraph + its schema |
+| `sl subgraphs scaffold <SP...::contract>` | Generate a starter subgraph from a deployed contract |
+| `sl subgraphs generate <name>` | Regenerate TS types for an existing subgraph |
+
+### Local dev + OSS
+
+| Command | What it does |
+|---|---|
+| `sl local start/stop/restart/status/logs` | Manage the local Docker stack |
+| `sl local node setup/start/stop/...` | Manage the local Stacks node |
+| `sl stack start/stop/restart` | Alias for `sl local` |
+| `sl db blocks/txs/events/gaps/reset/resync` | Inspect the local source DB |
+
+### Other
+
+| Command | What it does |
+|---|---|
+| `sl generate [files...]` (aliases: `gen`, `codegen`) | Generate TS interfaces from Clarity contracts |
+| `sl init` | Scaffold `secondlayer.config.ts` |
+| `sl doctor` | Session + project + instance reachability check |
+| `sl status` | Platform/instance health |
+| `sl account profile` | Update display name / bio / slug |
+| `sl config show/set/reset/clear` | Inspect or reset local config |
+
+## Environment variables
+
+| Var | Purpose |
+|---|---|
+| `SL_API_URL` | Bypass platform resolution — point at an OSS or internal API directly |
+| `SL_SERVICE_KEY` | Service key when using env-var bypass |
+| `SL_PLATFORM_API_URL` | Override the platform API base (default `https://api.secondlayer.tools`) |
+| `STACKS_NETWORK` | Override via `--network <local\|testnet\|mainnet>` |
+| `HIRO_API_KEY` | Used by `sl generate` for remote contract fetches |
+
+## Error codes
+
+Every tenant-scoped failure surfaces a typed code and an action hint:
+
+| Code | CLI hint |
+|---|---|
+| `SESSION_EXPIRED` | `Session expired. Run: sl login` |
+| `TENANT_SUSPENDED` | `Instance is suspended. Run: sl instance resume` |
+| `NO_ACTIVE_PROJECT` | `No project selected. Run: sl project use <slug>` |
+| `NO_TENANT_FOR_PROJECT` | `Project has no instance. Run: sl instance create --plan launch` |
+| `KEY_ROTATED` | Handled transparently — `http.ts` re-mints and retries once |
+
+## Code generation (`sl generate`)
+
+Generate type-safe interfaces, functions, and optional React hooks from
+Clarity contracts — works against local `.clar` files, deployed contracts
+(network inferred from address prefix), or glob patterns.
+
+```bash
+# Local .clar files
+sl generate ./contracts/token.clar -o ./src/generated.ts
+
+# Deployed contracts (SP/SM → mainnet, ST/SN → testnet)
+sl generate SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.alex-vault -o ./src/generated.ts
+
+# Glob
+sl generate "./contracts/*.clar" -o ./src/generated.ts
+```
+
+Config-driven mode:
+
+```bash
+sl init          # creates secondlayer.config.ts
+sl generate      # regenerates from the config
+```
+
+```typescript
+// secondlayer.config.ts
+import { defineConfig } from "@secondlayer/cli"
+import { clarinet, actions, react } from "@secondlayer/cli/plugins"
+
+export default defineConfig({
+  out: "src/generated.ts",
+  plugins: [clarinet(), actions(), react()],
+})
+```
+
+### Plugins
+
+| Plugin | What it adds |
+|---|---|
+| `clarinet()` | Parse local Clarinet project |
+| `actions()` | `read.*` + `write.*` helpers on each contract |
+| `react()` | Typed React Query hooks (`useTokenTransfer`, `useTokenBalance`, etc.) |
+| `testing()` | Clarinet SDK test helpers |
+
+### Usage examples
+
+```typescript
+import { token } from "./generated/contracts"
+import { makeContractCall, fetchCallReadOnlyFunction } from "@stacks/transactions"
+
+// Works with @stacks/transactions directly:
+await makeContractCall({
+  ...token.transfer({ amount: 100n, recipient: "SP..." }),
+  network: "mainnet",
+})
+
+// With actions() plugin — read/write helpers:
+const balance = await token.read.getBalance({ account: "SP..." })
+await token.write.transfer({ amount: 100n, recipient: "SP..." })
+
+// Maps / vars / constants:
+const supply = await token.vars.totalSupply.get()
+const bal = await token.maps.balances.get("SP...")
+const max = await token.constants.maxSupply.get()
+```
+
+```typescript
+// With react() plugin:
+import { useTokenTransfer, useTokenBalance } from "./generated/hooks"
+
+function App() {
+  const { transfer, isRequestPending } = useTokenTransfer()
+  const { data: balance } = useTokenBalance("SP...")
+  // ...
+}
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -2583,8 +2583,8 @@ function isOssMode() {
   return !!process.env.SL_API_URL && !process.env.SL_SERVICE_KEY;
 }
 var init_resolve_tenant = __esm(() => {
-  init_http();
   init_config();
+  init_http();
   init_project_file();
 });
 
@@ -32410,7 +32410,7 @@ var {
 // package.json
 var package_default = {
   name: "@secondlayer/cli",
-  version: "3.1.0",
+  version: "3.1.2-alpha.0",
   description: "CLI for subgraphs and blockchain indexing on Stacks",
   type: "module",
   bin: {
@@ -32431,7 +32431,8 @@ var package_default = {
   },
   files: [
     "dist",
-    "templates"
+    "templates",
+    "README.md"
   ],
   scripts: {
     build: "bunup",
@@ -32451,12 +32452,11 @@ var package_default = {
   license: "MIT",
   dependencies: {
     "@inquirer/prompts": "^8.2.0",
-    "@secondlayer/bundler": "^0.3.0",
-    "@secondlayer/sdk": "^2.0.0",
-    "@secondlayer/shared": "^2.1.0",
-    "@secondlayer/stacks": "^0.3.0",
-    "@secondlayer/subgraphs": "^0.11.8",
-    "@secondlayer/workflows": "^1.1.0",
+    "@secondlayer/bundler": "^0.3.1-alpha.0",
+    "@secondlayer/sdk": "^3.0.0-alpha.0",
+    "@secondlayer/shared": "^3.0.0-alpha.0",
+    "@secondlayer/stacks": "^1.0.0-alpha.0",
+    "@secondlayer/subgraphs": "^1.0.0-alpha.0",
     "@biomejs/js-api": "^0.7.0",
     "@biomejs/wasm-nodejs": "^1.9.0",
     esbuild: "^0.19.0",
@@ -32487,11 +32487,6 @@ function handleApiError(err, action) {
       console.error("Session expired. Run: sl login");
       process.exit(1);
     }
-    if (err.code === "TRIAL_EXPIRED") {
-      console.error(err.message);
-      console.error("Run: sl instance resize --plan <...> and add payment");
-      process.exit(1);
-    }
     if (err.code === "TENANT_SUSPENDED") {
       console.error("Tenant is suspended. Run: sl instance resume");
       process.exit(1);
@@ -34933,13 +34928,9 @@ function registerWhoamiCommand(program2) {
     try {
       const tenant = await httpPlatform("/api/tenants/me");
       if (tenant.tenant) {
-        const trialDays = Math.max(0, Math.ceil((new Date(tenant.tenant.trialEndsAt).getTime() - Date.now()) / (24 * 60 * 60 * 1000)));
         rows.push(["Instance", tenant.tenant.apiUrl]);
+        rows.push(["Plan", tenant.tenant.plan]);
         rows.push(["Status", tenant.tenant.status]);
-        rows.push([
-          "Trial",
-          `${trialDays} day${trialDays === 1 ? "" : "s"} left`
-        ]);
       } else {
         rows.push([
           "Instance",
@@ -35037,12 +35028,12 @@ init_resolve_tenant();
 import { confirm as confirm4, input as input3, select as select3 } from "@inquirer/prompts";
 function registerInstanceCommand(program2) {
   const instance = program2.command("instance").description("Manage your dedicated Secondlayer instance");
-  instance.command("create").description("Provision a new dedicated instance for the active project").option("--plan <plan>", "Plan: launch | grow | scale", "launch").action(async (opts) => {
+  instance.command("create").description("Provision a new dedicated instance for the active project").option("--plan <plan>", "Plan: hobby (free) | launch | grow | scale", "hobby").action(async (opts) => {
     guardOssMode();
     const activeSlug = await requireActiveProject();
     const plan = opts.plan;
-    if (!["launch", "grow", "scale"].includes(plan)) {
-      error(`Invalid plan: ${plan} (expected launch, grow, or scale)`);
+    if (!["hobby", "launch", "grow", "scale"].includes(plan)) {
+      error(`Invalid plan: ${plan} (expected hobby, launch, grow, or scale)`);
       process.exit(1);
     }
     try {
@@ -35060,13 +35051,17 @@ function registerInstanceCommand(program2) {
     guardOssMode();
     await renderInstanceInfo();
   });
-  instance.command("resize").description("Change your instance plan (brief downtime)").option("--plan <plan>", "Target plan: launch | grow | scale").option("--yes", "Skip confirm").action(async (opts) => {
+  instance.command("resize").description("Change your instance plan (brief downtime)").option("--plan <plan>", "Target plan: hobby | launch | grow | scale").option("--yes", "Skip confirm").action(async (opts) => {
     guardOssMode();
     let target = opts.plan;
     if (!target) {
       const answer = await select3({
         message: "Target plan",
         choices: [
+          {
+            value: "hobby",
+            name: "Hobby — free (0.5 vCPU · 512 MB · 5 GB, auto-pause after 7d idle)"
+          },
           {
             value: "launch",
             name: "Launch — $99/mo (1 vCPU · 2 GB · 10 GB)"
@@ -35268,12 +35263,10 @@ async function renderInstanceInfo() {
       return;
     }
     const t = res.tenant;
-    const trialDays = Math.max(0, Math.ceil((new Date(t.trialEndsAt).getTime() - Date.now()) / (24 * 60 * 60 * 1000)));
     console.log(formatKeyValue([
       ["URL", t.apiUrl],
       ["Plan", t.plan],
       ["Status", t.status],
-      ["Trial", `${trialDays} day${trialDays === 1 ? "" : "s"} left`],
       ["Created", new Date(t.createdAt).toLocaleString()]
     ]));
   } catch (err) {
@@ -35307,11 +35300,6 @@ function handleInstanceError(err, action) {
       error("Session expired. Run: sl login");
       process.exit(1);
     }
-    if (err.code === "TRIAL_EXPIRED") {
-      error(err.message);
-      error("Add a payment method at the dashboard to keep your instance running.");
-      process.exit(1);
-    }
     if (err.code === "TENANT_SUSPENDED") {
       error("Instance is suspended. Run: sl instance resume");
       process.exit(1);
@@ -35344,7 +35332,7 @@ function registerProjectCommand(program2) {
       success(`Created project ${res.project.name} (${res.project.slug})`);
       const path = await writeActiveProject(res.project.slug, process.cwd());
       info(dim(`Bound to this directory → ${path}`));
-      info(dim(`Next: sl instance create --plan launch`));
+      info(dim("Next: sl instance create --plan launch"));
     } catch (err) {
       handleProjectError(err);
     }
@@ -35448,5 +35436,5 @@ registerLocalCommand(program);
 registerAccountCommand(program);
 program.parse();
 
-//# debugId=395566BC0854202D64756E2164756E21
+//# debugId=2929270B62E4733C64756E2164756E21
 //# sourceMappingURL=cli.js.map