@tgcloud/cli 0.1.0

package/src/templates/docs/tgcloud-sdk.md

@@ -0,0 +1,347 @@
+# tgcloud SDK reference
+
+Everything your bot's modules can import from `sdk`: the database (`db`), the
+Telegram Bot API (`api`), HTTP (`fetch`), and `console` logging. The database is
+the largest surface, so it comes first; `api`, `fetch`, and `console` are at the
+end.
+
+> Orientation and project rules live in [../AGENTS.md](../AGENTS.md). This file is
+> the API reference.
+
+## `sdk` at a glance
+
+```js
+import { db, api, fetch, BotApiError } from 'sdk'
+// or from submodules:
+import { table, integer, text, eq, sql } from 'sdk/db'
+import { api } from 'sdk/api'
+import { fetch } from 'sdk/fetch'
+```
+
+- **`db`** — SQLite query builder + schema DSL. → most of this file.
+- **`api`** — Telegram Bot API (`api.sendMessage(...)`). → *Telegram Bot API* below.
+- **`fetch`** — outbound HTTP. → *HTTP* below.
+- **`console`** — logging that surfaces in `npx tgcloud run` output. → *Logging* below.
+
+## Rules that bite
+
+The runtime is not stock Node — these defaults don't hold. Detail is in the
+sections below; project rules are in [../AGENTS.md](../AGENTS.md).
+
+- **Import by bare module name** — `from 'schema'`, `from 'lib/cart'`, `from 'sdk/db'`. Never a relative path or a `.js` extension.
+- **Every DB call is async — always `await`.** `.all()`/`.get()`/`.values()`/`.run()`, `db.$count()`, and raw `db.run/all/get` all return Promises. A forgotten `await` returns the builder, not rows.
+- **No foreign keys.** `.references()` and table-level `foreignKey()` **throw when declared** — a schema using them won't deploy. Enforce integrity in app code.
+- **Drops happen only via `.deprecated('reason')`** on a column/table/index. Deleting the declaration does *not* drop it; type changes are manual (`db.run(...)`).
+- **A handler's `export default (input, ctx)`** gets the update's *payload* as `input` — `handlers/message` receives the `Message` (i.e. `update.message`), `handlers/callback_query` the `CallbackQuery`. The full `Update` (with `update_id`) is `ctx.update`.
+
+# Database (`db`)
+
+## Importing
+
+`db` (the default export of `sdk/db`) holds the whole API; the same functions are
+also named exports.
+
+```js
+import { table, integer, text, eq, sql } from 'sdk/db'   // named imports
+import db, { sql } from 'sdk/db'                          // or namespace + names
+```
+
+Import your own modules by **bare name** — `from 'schema'`, `from 'lib/cart'` —
+never a relative path or `.js` extension.
+
+## Defining the schema (`schema.js`)
+
+Tables are **named exports**. `table()` builds a descriptor at runtime (no DB call);
+the platform discovers the exported tables and runs migrations when you deploy
+`schema.js`.
+
+```js
+import { table, integer, text, boolean, json, index, check, sql } from 'sdk/db'
+
+export const users = table('users', {
+  id:      integer('id').primaryKey({ autoIncrement: true }),
+  tgId:    integer('tg_id').unique(),
+  name:    text('name').notNull(),
+  lang:    text('lang').default('en'),
+  isAdmin: boolean('is_admin').default(false),
+  prefs:   json('prefs'),
+  created: integer('created_at', { mode: 'timestamp' }).default(sql`(unixepoch())`),
+}, (t) => ({
+  createdIdx: index('idx_users_created').on(t.created),
+}))
+
+export const todos = table('todos', {
+  id:     integer('id').primaryKey({ autoIncrement: true }),
+  userId: integer('user_id').notNull(),   // logical link to users.id — FKs are NOT enforced
+  text:   text('text').notNull(),
+  done:     boolean('done').default(false),
+  priority: integer('priority').default(0),
+}, (t) => ({
+  userDoneIdx:   index('idx_todos_user_done').on(t.userId, t.done),
+  priorityCheck: check('priority_check', sql`${t.priority} >= 0`),
+}))
+```
+
+The third argument to `table()` is a callback `(t) => ({...})` where `t` exposes the
+columns (`t.userId` → a column ref); declare indexes and table-level constraints there.
+
+## Column types
+
+| factory     | SQLite | notes                                          |
+|-------------|--------|------------------------------------------------|
+| `text()`    | TEXT   |                                                |
+| `integer()` | INTEGER|                                                |
+| `real()`    | REAL   | alias `float()`                                |
+| `numeric()` | NUMERIC|                                                |
+| `blob()`    | BLOB   | takes/returns `Uint8Array`                     |
+| `boolean()` | INTEGER| stored 0/1, read as `true`/`false`             |
+| `json()`    | TEXT   | auto `JSON.stringify` / `JSON.parse`           |
+
+Signature: `integer(name?, opts?)`. The name is optional — if omitted it's taken
+from the JS key. `opts.mode` sets runtime conversion:
+
+| mode           | stored as          | JS value              |
+|----------------|--------------------|-----------------------|
+| `boolean`      | INTEGER 0/1        | `boolean`             |
+| `json`         | TEXT (JSON)        | any object/array      |
+| `timestamp`    | INTEGER (unix sec) | `Date`                |
+| `timestamp_ms` | INTEGER (unix ms)  | `Date`                |
+| `bytes`        | BLOB               | `Uint8Array`          |
+
+`boolean()` and `json()` are sugar over `integer(name, { mode: 'boolean' })` and
+`text(name, { mode: 'json' })`. A `blob()` column takes and returns a `Uint8Array`
+automatically — that's handled at the wire level, so it needs no mode.
+
+## Column modifiers (chainable)
+
+```js
+integer('id').primaryKey()
+integer('id').primaryKey({ autoIncrement: true })
+text('name').notNull()
+text('tg').unique()
+text('lang').default('en')
+integer('created_at', { mode: 'timestamp' }).default(sql`(unixepoch())`)
+text('slug').generatedAlwaysAs(sql`lower(name)`, { mode: 'stored' })  // 'virtual' | 'stored'
+text('name').constraint('COLLATE NOCASE')       // arbitrary column-level DDL
+text('email').deprecated('replaced by login')   // marks for drop; invisible at runtime
+```
+
+- `.default()` on a `json()` column encodes the value automatically; a `` sql`...` ``
+  default is passed through verbatim.
+- `.deprecated()` is terminal — don't chain methods after it.
+
+## No foreign keys
+
+The runtime runs with `PRAGMA foreign_keys` **off**, so a declared FK would be
+silently inert (no cascades, no orphan protection). To make that impossible,
+`.references()` and table-level `foreignKey()` **throw when declared** — a schema
+using them won't deploy. `REFERENCES`/`FOREIGN KEY` smuggled in via `.constraint()`
+or a raw `db.run('CREATE TABLE …')` stay inert too. Enforce integrity in app code:
+delete children before parents, insert parents before children, sweep orphans with
+`LEFT JOIN … WHERE parent.id IS NULL`.
+
+## Table-level constraints & indexes (in the callback)
+
+```js
+table('t', { ... }, (t) => ({
+  pk:    primaryKey({ columns: [t.a, t.b] }),
+  uq:    unique('uq_email').on(t.email),
+  chk:   check('chk_done', sql`${t.done} in (0, 1)`),
+  idx:   index('idx_name').on(t.col),
+  uidx:  uniqueIndex('uidx_email').on(t.email),
+  lower: index('idx_lower').on(sql`lower(${t.email})`),          // expression index
+  active:index('idx_active').on(t.userId).where(sql`done = 0`),  // partial index
+  // foreignKey(...) is NOT supported — it throws (see "No foreign keys")
+}))
+```
+
+Table modifiers (chained after `table(...)`): `.strict()`, `.withoutRowid()`,
+`.constraint('CHECK (x > 0)', 'chk_x')`, `.deprecated('reason')`.
+
+## Query builder
+
+### select
+
+`select(projection?)` → `.from(table)` → builder. No projection = `SELECT *`.
+
+```js
+await db.select().from(todos).all()                          // all rows
+await db.select().from(todos).where(eq(todos.id, 1)).get()   // first row or null
+await db.$count(todos)                                        // COUNT(*)
+
+await db.select().from(todos)
+  .where(and(eq(todos.userId, uid), eq(todos.done, false)))
+  .orderBy(desc(todos.priority), asc(todos.id))
+  .limit(10).offset(20)
+  .all()
+
+// projection: { alias: colRef | sqlExpr }
+await db.select({ id: todos.id, title: todos.text, n: sql`count(*)` })
+  .from(todos).groupBy(todos.userId).having(sql`count(*) > ${1}`).all()
+```
+
+Chain: `.where()` `.orderBy()` `.limit()` `.offset()` `.groupBy()` `.having()`
+`.distinct()`; terminals `.all()` / `.get()` / `.values()`.
+
+The builder is **awaitable** — `await db.select().from(todos)` (with `.where(…)`
+etc. as needed) runs `.all()` and resolves to the row array, so `.all()` is
+optional. Use `.get()`/`.values()` for the other shapes; count rows with
+`db.$count(table, where?)`.
+
+### insert / update / delete
+
+```js
+await db.insert(todos).values({ userId: 1, text: 'Buy milk' }).run()
+await db.insert(todos).values([{ text: 'A' }, { text: 'B' }]).run()   // batch
+await db.insert(todos).values({ text: 'X' }).returning().run()        // RETURNING *
+
+await db.insert(users).values({ tgId: 42, name: 'Ann' })
+  .onConflictDoNothing({ target: users.tgId }).run()
+await db.insert(users).values({ tgId: 42, name: 'Ann' })
+  .onConflictDoUpdate({ target: users.tgId, set: { name: 'Ann' } }).run()
+
+await db.update(todos).set({ done: true }).where(eq(todos.id, 1)).run()   // .set() required
+await db.delete(todos).where(eq(todos.id, 1)).run()
+```
+
+A plain insert/update/delete resolves to `[]` — there's no insert id or row count.
+Add `.returning()` (→ `RETURNING *`) or `.returning({ id: todos.id })` to get the
+affected rows back (converted, since they're bound to the table). Like select,
+these builders are **awaitable**: `await db.insert(todos).values({ … })` runs
+without an explicit `.run()`.
+
+### Raw SQL — `db.run` / `db.all` / `db.get`
+
+Mode is by method, not auto-detected: `run` = write/exec, `all` = all rows,
+`get`/`one` = first row (or `null`). Each takes a `` sql`…` `` object or a
+`(queryString, params)` pair.
+
+```js
+await db.run('UPDATE todos SET done = 1 WHERE id = :id', { ':id': 5 })
+await db.all(sql`SELECT * FROM todos WHERE done = ${false}`)
+await db.get(sql`SELECT count(*) AS c FROM todos`)
+```
+
+> Raw methods are **not bound to a table**, so rows come back without mode
+> conversion (boolean/json/timestamp arrive as 0/1, a JSON string, unix seconds).
+> Only the table-bound builder converts.
+
+`db.raw.read(sql, params)` / `db.raw.write(sql, params)` are the low-level escape
+hatch (params default `{}`); prefer `run`/`all`/`get` above.
+
+## `sql` tagged template
+
+`` sql`...` `` interpolates values as named parameters, column refs as identifiers,
+and splices nested `sql`.
+
+```js
+sql`count = ${n}`                 // count = :p1
+sql`${todos.priority} > ${min}`   // priority > :p2  (column as identifier)
+sql`WHERE ${cond}`                // nested sql spliced in
+sql.raw('datetime("now")')        // literal, no parameters
+```
+
+In DDL contexts (DEFAULT / CHECK / GENERATED) parameters don't work — use literal SQL.
+
+## Operators
+
+Import from `sdk/db`:
+
+```js
+import {
+  eq, ne, gt, gte, lt, lte,
+  like, notLike,
+  isNull, isNotNull, and, or, not,
+  between, notBetween, inArray, notInArray,
+  count, sum, avg, min, max,
+  asc, desc,
+} from 'sdk/db'
+```
+
+`.where(e1, e2)` with multiple args is equivalent to `and(e1, e2)`.
+
+## Migrations (summary)
+
+- **Adding** columns/tables/indexes — applied automatically on `npx tgcloud migrate`
+  after you deploy `schema.js`.
+- **Dropping** — only via `.deprecated()`; the CLI shows what will be removed.
+- **Changing a column's type** — not automatic; do it manually with `db.run`.
+
+`npx tgcloud push` reports pending DB changes but never applies them. Run
+`npx tgcloud migrate` to apply.
+
+# Telegram Bot API (`api`)
+
+`import { api, BotApiError } from 'sdk'`. Call any Bot API method as
+`api.<method>(params)` — a Proxy dispatches the name, so every current (and
+future) method works with no SDK update.
+
+```js
+const me = await api.getMe()                          // → the unwrapped `result`
+await api.sendMessage({ chat_id: id, text: 'Hello!' })
+await api.editMessageText({ chat_id, message_id, text: 'Updated' })
+await api.answerCallbackQuery({ callback_query_id, text: 'Done' })
+```
+
+- **The envelope is unwrapped.** On `{ ok: true }` the call resolves to `result`
+  directly — no `.ok`/`.result` wrapper. Params are one object using the Bot API's
+  snake_case names (`chat_id`, `message_id`, …).
+- **Failures throw `BotApiError`.** On `{ ok: false }` it throws; the error carries
+  `.code` (Bot API `error_code` — 400/403/429/…), `.description`, `.method`, and
+  `.parameters` (e.g. `retry_after` on 429, `migrate_to_chat_id`). Catch and inspect
+  `.code` to handle an expected failure:
+
+```js
+try {
+  await api.deleteMessage({ chat_id, message_id });
+} catch (e) {
+  if (e.code !== 400) throw e;   // 400 = already gone; anything else is a real error
+}
+```
+
+# HTTP (`fetch`)
+
+`import { fetch } from 'sdk'`. A `fetch`-like client for outbound HTTP.
+
+```js
+const res = await fetch('https://api.example.com/users', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ name: 'Alice' }),
+});
+if (!res.ok) throw new Error(res.statusText);
+const data = await res.json();
+```
+
+The response: `res.status`, `res.statusText`, `res.ok` (true for 200–299),
+`res.url`, `res.headers` (`.get()` / `.has()` / `.keys()` / `.entries()`), and body
+readers `await res.json()` / `await res.text()`. Or stream:
+`for await (const chunk of res.body)`.
+
+Body helpers set the matching `Content-Type` for you:
+
+```js
+await fetch(url, { method: 'POST', body: fetch.body.json({ a: 1 }) }); // application/json
+await fetch(url, { method: 'POST', body: fetch.body.form({ a: 1 }) }); // x-www-form-urlencoded
+await fetch(url, { method: 'POST', body: fetch.body.text('hi') });     // text/plain
+```
+
+Notes: a body can be read **once** — a second `.json()`/`.text()`/stream throws
+`TypeError: body used already` (check `res.bodyUsed`). Redirects are followed
+automatically (web-parity) — `res.url` is the final URL after any hops. A 404 (or
+any HTTP status) resolves normally with `res.ok === false`; only real network
+errors (bad host, invalid URL) reject.
+
+# Logging (`console`)
+
+Plain `console` works, and its output shows up in `npx tgcloud run`:
+
+```js
+console.log('processing', { chatId: id });  // log / debug — plain
+console.info('started');                     // info  — blue
+console.warn('rate limited');                // warn  — yellow
+console.error(err);                          // error — red, includes a stack
+```
+
+Each line is tagged with its `[file:line]`. `console.error` and `console.trace`
+append a full stack trace; `console.warn` does not.

package/src/templates/gitignore

@@ -0,0 +1,2 @@
+.tgcloud/
+node_modules/

package/src/templates/handlers/_default_.js

@@ -0,0 +1,6 @@
+// handlers/$$BASENAME$$ — runs on each `$$BASENAME$$` update.
+import { api } from 'sdk';
+
+export default async function ($$BASENAME$$, ctx) {
+  // your logic here
+}

package/src/templates/handlers/message.js

@@ -0,0 +1,13 @@
+// handlers/message.js — runs on each `message` update. The file name is the
+// Telegram update type; the platform calls the default export with the matching
+// payload (here, a Message). The full update is available as `ctx.update`.
+
+import { api } from 'sdk';
+
+export default async function (message, ctx) {
+  // Echo the text back — replace with your own logic.
+  await api.sendMessage({
+    chat_id: message.chat.id,
+    text: `You said: ${message.text ?? '(no text)'}`,
+  });
+}

package/src/templates/lib/_default_.js

@@ -0,0 +1,2 @@
+// $$MODULE$$ — shared module. Export functions or values below, then import
+// them elsewhere by module name: import { thing } from '$$MODULE$$';

package/src/templates/schema.js

@@ -0,0 +1,10 @@
+import { table, integer, text } from 'sdk/db';
+
+// Your database tables go here as named exports. `npx tgcloud push` deploys this
+// file; `npx tgcloud migrate` applies the changes to the database.
+
+// Uncomment to define your first table:
+// export const users = table('users', {
+//   id:   integer('id').primaryKey({ autoIncrement: true }),
+//   name: text('name').notNull(),
+// });

package/src/utils/logger.js

@@ -0,0 +1,54 @@
+import chalk from 'chalk';
+
+export function success(msg) {
+  console.log(chalk.green('  ✓ ') + msg);
+}
+
+// Non-fatal error line. Convention: only the "Error:" word is colored, the
+// message stays default — matches fatal(). Glyphs (✓/✗) are reserved for
+// formatted lists (created files, deploy status), not message-level output.
+export function error(msg) {
+  // Errors go to stderr (like fatal()), so a script capturing stdout doesn't mix
+  // error text into normal output.
+  console.error(chalk.red('Error: ') + msg);
+}
+
+export function warn(msg) {
+  console.log(chalk.yellow('Warning: ') + msg);
+}
+
+export function info(msg) {
+  console.log(msg);
+}
+
+export function modified(file) {
+  console.log(chalk.yellow('  ↑ ') + file + chalk.dim(' — modified'));
+}
+
+export function newFile(file) {
+  console.log(chalk.green('  + ') + file + chalk.dim(' — new'));
+}
+
+export function unchanged(file) {
+  console.log(chalk.green('  ✓ ') + file + chalk.dim(' — unchanged'));
+}
+
+export function deleted(file) {
+  console.log(chalk.red('  - ') + file + chalk.dim(' — deleted'));
+}
+
+export function skipped(file, reason) {
+  console.log(chalk.red('  ✗ ') + file + chalk.dim(` — ${reason}`));
+}
+
+// A completed per-file action: green ✓, the path, then a dim "— status" suffix.
+// Pairs with skipped() (red ✗). Use for deploy/pull/reset result lines so the
+// status reads as dim metadata, consistent with modified()/newFile()/deleted().
+export function done(file, status) {
+  console.log(chalk.green('  ✓ ') + file + (status ? chalk.dim(` — ${status}`) : ''));
+}
+
+export function fatal(msg) {
+  console.error(chalk.red('Error: ') + msg);
+  process.exit(1);
+}

package/src/utils/pager.js

@@ -0,0 +1,76 @@
+import { spawn } from 'child_process';
+
+/**
+ * Launch a pager (like git does) if:
+ *   - stdout is a TTY,
+ *   - not explicitly disabled (via options.disabled),
+ *   - PAGER env var is not empty / not set to something trivial.
+ *
+ * Returns an object with `write(str)` and async `close()`.
+ * Fallback to plain stdout if the pager can't be launched.
+ *
+ * Usage:
+ *   const pager = createPager({ disabled: options.pager === false });
+ *   pager.write('line\n');
+ *   await pager.close();
+ */
+export function createPager({ disabled = false } = {}) {
+  // Fallback: write directly to stdout, no pager involvement.
+  const stdoutFallback = {
+    write: (s) => process.stdout.write(s),
+    close: async () => {},
+  };
+
+  if (disabled) return stdoutFallback;
+  if (process.env.TGCLOUD_NO_PAGER === '1') return stdoutFallback;
+  if (!process.stdout.isTTY) return stdoutFallback;
+
+  // Resolve pager command.
+  // Convention: empty/unset PAGER → default to `less`. "cat" disables paging.
+  const raw = process.env.PAGER;
+  if (raw === '' || raw === 'cat') return stdoutFallback;
+
+  const cmd = raw && raw.trim() ? raw : 'less';
+
+  // Split into argv if PAGER had args; otherwise add sensible defaults for less.
+  let argv;
+  if (raw && raw.includes(' ')) {
+    const parts = raw.split(/\s+/).filter(Boolean);
+    argv = parts;
+  } else if (cmd === 'less') {
+    // -R: keep ANSI colors, -F: quit-if-one-screen, -X: no alt-screen clear
+    argv = ['less', '-R', '-F', '-X'];
+  } else {
+    argv = [cmd];
+  }
+
+  let child;
+  try {
+    child = spawn(argv[0], argv.slice(1), { stdio: ['pipe', 'inherit', 'inherit'] });
+  } catch {
+    return stdoutFallback;
+  }
+
+  // If user quits the pager with `q` while we're still writing, stdin closes
+  // and further writes raise EPIPE. Swallow those — expected behavior.
+  let closed = false;
+  child.stdin.on('error', (err) => {
+    if (err?.code === 'EPIPE') { closed = true; return; }
+    // Other errors — leave to default handler.
+  });
+  child.on('exit', () => { closed = true; });
+  child.on('error', () => { closed = true; });
+
+  return {
+    write: (s) => {
+      if (closed) return;
+      try { child.stdin.write(s); } catch { /* EPIPE */ }
+    },
+    close: () => new Promise((resolve) => {
+      if (closed) { resolve(); return; }
+      try { child.stdin.end(); } catch {}
+      if (child.exitCode != null) { resolve(); return; }
+      child.once('exit', resolve);
+    }),
+  };
+}