@vsceasy/cli 0.1.0

package/templates/_generators/helper/cache.ts.tpl

@@ -0,0 +1,117 @@
+/**
+ * In-memory TTL + LRU cache. Pair with the ORM for cheap reads:
+ *
+ *   const cache = createCache<User>({ ttlMs: 60_000, max: 200 });
+ *   const u = await cache.wrap(`user:${id}`, () => orm(User).findById(id));
+ *
+ * Survives only while the extension host is running (cleared on reload).
+ * For persistent caches, write through to the ORM or `globalState`.
+ */
+
+export interface CacheOptions {
+  /** Time-to-live in ms. 0 = never expire. Default: 60000. */
+  ttlMs?: number;
+  /** Max entries. LRU eviction once exceeded. 0 = unlimited. Default: 500. */
+  max?: number;
+}
+
+export interface Cache<V> {
+  get(key: string): V | undefined;
+  set(key: string, value: V, ttlMsOverride?: number): void;
+  delete(key: string): boolean;
+  has(key: string): boolean;
+  clear(): void;
+  /** Memoize a loader. Returns cached value if fresh, else runs `fn` and stores. */
+  wrap(key: string, fn: () => Promise<V>, ttlMsOverride?: number): Promise<V>;
+  /** Force-refresh: invalidate then wrap. */
+  refresh(key: string, fn: () => Promise<V>, ttlMsOverride?: number): Promise<V>;
+  readonly size: number;
+}
+
+interface Entry<V> {
+  value: V;
+  expiresAt: number; // 0 = no expiry
+}
+
+export function createCache<V = unknown>(opts: CacheOptions = {}): Cache<V> {
+  const ttl = opts.ttlMs ?? 60_000;
+  const max = opts.max ?? 500;
+  // Map preserves insertion order — re-insert on access for LRU behavior.
+  const store = new Map<string, Entry<V>>();
+  // De-dupe concurrent loads for the same key.
+  const inflight = new Map<string, Promise<V>>();
+
+  const isFresh = (e: Entry<V>) => e.expiresAt === 0 || e.expiresAt > Date.now();
+
+  const evictIfNeeded = () => {
+    if (max <= 0) return;
+    while (store.size > max) {
+      const oldest = store.keys().next().value;
+      if (oldest === undefined) break;
+      store.delete(oldest);
+    }
+  };
+
+  const cache: Cache<V> = {
+    get(key) {
+      const e = store.get(key);
+      if (!e) return undefined;
+      if (!isFresh(e)) {
+        store.delete(key);
+        return undefined;
+      }
+      // LRU touch
+      store.delete(key);
+      store.set(key, e);
+      return e.value;
+    },
+    set(key, value, ttlMsOverride) {
+      const t = ttlMsOverride ?? ttl;
+      store.delete(key); // re-insert for LRU order
+      store.set(key, { value, expiresAt: t > 0 ? Date.now() + t : 0 });
+      evictIfNeeded();
+    },
+    delete(key) {
+      return store.delete(key);
+    },
+    has(key) {
+      const e = store.get(key);
+      if (!e) return false;
+      if (!isFresh(e)) {
+        store.delete(key);
+        return false;
+      }
+      return true;
+    },
+    clear() {
+      store.clear();
+      inflight.clear();
+    },
+    async wrap(key, fn, ttlMsOverride) {
+      const cached = cache.get(key);
+      if (cached !== undefined) return cached;
+      const pending = inflight.get(key);
+      if (pending) return pending;
+      const p = (async () => {
+        try {
+          const v = await fn();
+          cache.set(key, v, ttlMsOverride);
+          return v;
+        } finally {
+          inflight.delete(key);
+        }
+      })();
+      inflight.set(key, p);
+      return p;
+    },
+    async refresh(key, fn, ttlMsOverride) {
+      cache.delete(key);
+      return cache.wrap(key, fn, ttlMsOverride);
+    },
+    get size() {
+      return store.size;
+    },
+  };
+
+  return cache;
+}

package/templates/_generators/helper/config.ts.tpl

@@ -0,0 +1,36 @@
+import * as vscode from 'vscode';
+
+/**
+ * Typed wrapper over `vscode.workspace.getConfiguration('{{commandPrefix}}')`.
+ * Reads settings declared under `contributes.configuration` in package.json.
+ *
+ * Example package.json snippet:
+ *   "contributes": {
+ *     "configuration": {
+ *       "title": "{{displayName}}",
+ *       "properties": {
+ *         "{{commandPrefix}}.apiUrl": { "type": "string", "default": "" }
+ *       }
+ *     }
+ *   }
+ *
+ * Usage:
+ *   const url = config.get<string>('apiUrl');
+ *   await config.set('apiUrl', 'https://...');
+ */
+const SECTION = '{{commandPrefix}}';
+
+export const config = {
+  get<T>(key: string, fallback?: T): T {
+    const v = vscode.workspace.getConfiguration(SECTION).get<T>(key);
+    return (v === undefined ? (fallback as T) : v) as T;
+  },
+  set(key: string, value: unknown, target: vscode.ConfigurationTarget = vscode.ConfigurationTarget.Global): Thenable<void> {
+    return vscode.workspace.getConfiguration(SECTION).update(key, value, target);
+  },
+  onChange(listener: (key: string) => void): vscode.Disposable {
+    return vscode.workspace.onDidChangeConfiguration((e) => {
+      if (e.affectsConfiguration(SECTION)) listener(SECTION);
+    });
+  },
+};

package/templates/_generators/helper/db.ts.tpl

@@ -0,0 +1,322 @@
+import * as vscode from 'vscode';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Mini-ORM with pluggable providers. Ships with a filesystem JSON provider that
+ * writes each entity to a single file under the extension's storage dir. Future
+ * providers (sqlite, etc.) implement the same `Provider` interface — entity
+ * definitions and call sites don't change.
+ *
+ * Usage:
+ *   const User = defineEntity<{ id: string; name: string }>('users', { primaryKey: 'id' });
+ *   const orm = createDb(context, { provider: 'storage' });
+ *   await orm(User).insert({ id: 'u1', name: 'Jairo' });
+ *   const u = await orm(User).findById('u1');
+ */
+
+// ── Entity definition ────────────────────────────────────────────────────────
+
+export interface EntityOptions<T> {
+  /** Field used as the unique key. */
+  primaryKey: keyof T & string;
+  /** Optional indexes — speeds up `findOne({ [k]: v })` for these fields. */
+  indexes?: (keyof T & string)[];
+}
+
+export interface Entity<T> {
+  readonly name: string;
+  readonly primaryKey: keyof T & string;
+  readonly indexes: (keyof T & string)[];
+  /** Phantom type carrier so `orm(E)` infers `T`. Never read. */
+  readonly __t?: T;
+}
+
+export function defineEntity<T extends object>(
+  name: string,
+  opts: EntityOptions<T>,
+): Entity<T> {
+  return { name, primaryKey: opts.primaryKey, indexes: opts.indexes ?? [] };
+}
+
+// ── Query types ──────────────────────────────────────────────────────────────
+
+export type Where<T> = Partial<{ [K in keyof T]: T[K] | { in: T[K][] } | { neq: T[K] } }>;
+
+export interface FindOptions<T> {
+  where?: Where<T>;
+  limit?: number;
+  offset?: number;
+  /** `'field:asc'` | `'field:desc'`. Default asc when only field given. */
+  orderBy?: `${keyof T & string}:${'asc' | 'desc'}` | (keyof T & string);
+}
+
+export interface Repository<T> {
+  findById(id: T[keyof T]): Promise<T | null>;
+  findOne(where: Where<T>): Promise<T | null>;
+  findMany(opts?: FindOptions<T>): Promise<T[]>;
+  count(opts?: { where?: Where<T> }): Promise<number>;
+  insert(row: T): Promise<T>;
+  upsert(row: T): Promise<T>;
+  update(id: T[keyof T], patch: Partial<T>): Promise<T | null>;
+  delete(id: T[keyof T]): Promise<boolean>;
+  deleteMany(where: Where<T>): Promise<number>;
+  clear(): Promise<void>;
+}
+
+// ── Provider interface (future-proof for sqlite/etc.) ────────────────────────
+
+export interface Provider {
+  load(entity: string): Promise<Record<string, unknown>[]>;
+  save(entity: string, rows: Record<string, unknown>[]): Promise<void>;
+  /** Atomic batch. Implementations may optimize. */
+  transaction(work: (snapshot: Map<string, Record<string, unknown>[]>) => Promise<void> | void): Promise<void>;
+}
+
+// ── Storage provider (filesystem JSON) ───────────────────────────────────────
+
+class StorageProvider implements Provider {
+  private cache = new Map<string, Record<string, unknown>[]>();
+
+  constructor(private readonly root: string) {
+    fs.mkdirSync(root, { recursive: true });
+  }
+
+  private fileFor(entity: string): string {
+    return path.join(this.root, `${entity}.json`);
+  }
+
+  async load(entity: string): Promise<Record<string, unknown>[]> {
+    if (this.cache.has(entity)) return this.cache.get(entity)!;
+    const f = this.fileFor(entity);
+    if (!fs.existsSync(f)) {
+      this.cache.set(entity, []);
+      return [];
+    }
+    try {
+      const rows = JSON.parse(fs.readFileSync(f, 'utf8'));
+      this.cache.set(entity, rows);
+      return rows;
+    } catch {
+      this.cache.set(entity, []);
+      return [];
+    }
+  }
+
+  async save(entity: string, rows: Record<string, unknown>[]): Promise<void> {
+    this.cache.set(entity, rows);
+    const f = this.fileFor(entity);
+    const tmp = `${f}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(rows));
+    fs.renameSync(tmp, f); // atomic on same filesystem
+  }
+
+  async transaction(
+    work: (snapshot: Map<string, Record<string, unknown>[]>) => Promise<void> | void,
+  ): Promise<void> {
+    // Snapshot pre-tx state for rollback. Working copy is what `work` mutates.
+    const backup = new Map<string, Record<string, unknown>[]>();
+    for (const [k, v] of this.cache) backup.set(k, structuredClone(v));
+    const working = new Map<string, Record<string, unknown>[]>();
+    for (const [k, v] of this.cache) working.set(k, structuredClone(v));
+    try {
+      await work(working);
+      for (const [entity, rows] of working) await this.save(entity, rows);
+    } catch (err) {
+      // Roll back in-memory cache to the pre-tx snapshot.
+      for (const [k, v] of backup) this.cache.set(k, v);
+      throw err;
+    }
+  }
+}
+
+// ── Public DB type ───────────────────────────────────────────────────────────
+
+export interface Db {
+  <T extends object>(entity: Entity<T>): Repository<T>;
+  transaction(work: (tx: Db) => Promise<void> | void): Promise<void>;
+  /** Wipe a single entity. */
+  drop(entity: Entity<unknown>): Promise<void>;
+  /** Underlying provider — escape hatch for advanced use. */
+  readonly provider: Provider;
+}
+
+export interface CreateDbOptions {
+  /** `'storage'` writes under `context.storageUri/<subdir>/`. `'global'` uses `globalStorageUri`. */
+  provider: 'storage' | 'global';
+  /** Override sub-directory under the chosen storage root. Default: `db`. */
+  subdir?: string;
+}
+
+export function createDb(ctx: vscode.ExtensionContext, opts: CreateDbOptions): Db {
+  // `storageUri` is only defined when a workspace/folder is open. `globalStorageUri`
+  // is always available — fall back to it so the extension still activates with no
+  // folder open (e.g. the Extension Development Host on first launch).
+  const baseUri =
+    opts.provider === 'global'
+      ? ctx.globalStorageUri
+      : (ctx.storageUri ?? ctx.globalStorageUri);
+  if (!baseUri) {
+    throw new Error('createDb: no storage URI available from the extension context.');
+  }
+  const root = path.join(baseUri.fsPath, opts.subdir ?? 'db');
+  const provider = new StorageProvider(root);
+  ctx.subscriptions.push({ dispose: () => {} }); // future hook
+  return makeDb(provider);
+}
+
+// ── Singleton accessor — `import { db } from './db'; await db()(Users).insert(...)` ──
+
+let _db: Db | undefined;
+
+/**
+ * Default options used by `initDb` when called as a bootstrap hook (one-arg).
+ * Override via the 2-arg form: `initDb(context, { provider: 'global' })`.
+ */
+export const dbOptions: CreateDbOptions = { provider: '{{provider}}' };
+
+/**
+ * Initialize the shared db. Call once on activate. Idempotent.
+ *
+ * As a bootstrap hook (recommended — `bootstrap(registry, { onActivate: [initDb] })`):
+ *   initDb(context)
+ *
+ * Direct call with custom options:
+ *   initDb(context, { provider: 'global' })
+ */
+export function initDb(ctx: vscode.ExtensionContext, opts?: CreateDbOptions): Db {
+  if (_db) return _db;
+  _db = createDb(ctx, opts ?? dbOptions);
+  return _db;
+}
+
+/** Access the shared db. Throws if `initDb()` wasn't called yet. */
+export function db(): Db {
+  if (!_db) throw new Error('db not initialized — call initDb(context) on activate.');
+  return _db;
+}
+
+function makeDb(provider: Provider): Db {
+  const repoFor = <T extends object>(entity: Entity<T>): Repository<T> => {
+    const pk = entity.primaryKey;
+    const load = () => provider.load(entity.name) as Promise<T[]>;
+    const save = (rows: T[]) => provider.save(entity.name, rows as Record<string, unknown>[]);
+
+    return {
+      async findById(id) {
+        const rows = await load();
+        return rows.find((r) => r[pk] === id) ?? null;
+      },
+      async findOne(where) {
+        const rows = await load();
+        return rows.find((r) => match(r, where)) ?? null;
+      },
+      async findMany(opts = {}) {
+        let rows = await load();
+        if (opts.where) rows = rows.filter((r) => match(r, opts.where!));
+        if (opts.orderBy) {
+          const [field, dir] = String(opts.orderBy).split(':');
+          const sign = dir === 'desc' ? -1 : 1;
+          rows = [...rows].sort((a, b) => compare(a[field as keyof T], b[field as keyof T]) * sign);
+        }
+        if (opts.offset) rows = rows.slice(opts.offset);
+        if (opts.limit !== undefined) rows = rows.slice(0, opts.limit);
+        return rows;
+      },
+      async count(opts = {}) {
+        const rows = await load();
+        return opts.where ? rows.filter((r) => match(r, opts.where!)).length : rows.length;
+      },
+      async insert(row) {
+        const rows = await load();
+        if (rows.some((r) => r[pk] === row[pk])) {
+          throw new Error(`${entity.name}: duplicate ${pk}=${String(row[pk])}`);
+        }
+        rows.push(row);
+        await save(rows);
+        return row;
+      },
+      async upsert(row) {
+        const rows = await load();
+        const i = rows.findIndex((r) => r[pk] === row[pk]);
+        if (i >= 0) rows[i] = row; else rows.push(row);
+        await save(rows);
+        return row;
+      },
+      async update(id, patch) {
+        const rows = await load();
+        const i = rows.findIndex((r) => r[pk] === id);
+        if (i < 0) return null;
+        rows[i] = { ...rows[i], ...patch };
+        await save(rows);
+        return rows[i];
+      },
+      async delete(id) {
+        const rows = await load();
+        const before = rows.length;
+        const next = rows.filter((r) => r[pk] !== id);
+        if (next.length === before) return false;
+        await save(next);
+        return true;
+      },
+      async deleteMany(where) {
+        const rows = await load();
+        const next = rows.filter((r) => !match(r, where));
+        const removed = rows.length - next.length;
+        if (removed > 0) await save(next);
+        return removed;
+      },
+      async clear() {
+        await save([]);
+      },
+    };
+  };
+
+  const db: Db = Object.assign(repoFor as any, {
+    provider,
+    async drop(entity: Entity<unknown>) {
+      await provider.save(entity.name, []);
+    },
+    async transaction(work: (tx: Db) => Promise<void> | void) {
+      await provider.transaction(async (snapshot) => {
+        // Build a tx-scoped Db that reads/writes the snapshot map.
+        const txProvider: Provider = {
+          async load(name) { return snapshot.get(name) ?? []; },
+          async save(name, rows) { snapshot.set(name, rows); },
+          async transaction() { throw new Error('Nested transactions are not supported'); },
+        };
+        await work(makeDb(txProvider));
+      });
+    },
+  });
+
+  return db;
+}
+
+// ── matcher ──────────────────────────────────────────────────────────────────
+
+function match<T extends object>(row: T, where: Where<T>): boolean {
+  for (const key of Object.keys(where) as (keyof T)[]) {
+    const expected = where[key] as unknown;
+    const actual = row[key];
+    if (expected && typeof expected === 'object' && !Array.isArray(expected)) {
+      if ('in' in expected) {
+        if (!(expected as { in: unknown[] }).in.includes(actual)) return false;
+        continue;
+      }
+      if ('neq' in expected) {
+        if (actual === (expected as { neq: unknown }).neq) return false;
+        continue;
+      }
+    }
+    if (actual !== expected) return false;
+  }
+  return true;
+}
+
+function compare(a: unknown, b: unknown): number {
+  if (a === b) return 0;
+  if (a === null || a === undefined) return -1;
+  if (b === null || b === undefined) return 1;
+  return a < b ? -1 : 1;
+}

package/templates/_generators/helper/notifications.ts.tpl

@@ -0,0 +1,45 @@
+import * as vscode from 'vscode';
+
+/**
+ * Concise wrappers over `vscode.window.show*Message`. Each accepts an optional
+ * list of action labels and resolves to the selected label (or undefined).
+ *
+ * Usage:
+ *   notify.info('Saved');
+ *   const pick = await notify.warn('Discard?', 'Discard', 'Keep');
+ *   if (pick === 'Discard') ...
+ *
+ * For long-running tasks use `withProgress`:
+ *   await withProgress('Indexing…', async (report) => {
+ *     for (let i = 0; i <= 100; i += 10) {
+ *       report({ increment: 10, message: `${i}%` });
+ *       await new Promise(r => setTimeout(r, 100));
+ *     }
+ *   });
+ */
+export const notify = {
+  info(message: string, ...actions: string[]) {
+    return vscode.window.showInformationMessage(message, ...actions);
+  },
+  warn(message: string, ...actions: string[]) {
+    return vscode.window.showWarningMessage(message, ...actions);
+  },
+  error(message: string, ...actions: string[]) {
+    return vscode.window.showErrorMessage(message, ...actions);
+  },
+  confirm(message: string, yesLabel = 'Yes', noLabel = 'No'): Thenable<boolean> {
+    return vscode.window
+      .showInformationMessage(message, { modal: true }, yesLabel, noLabel)
+      .then((pick) => pick === yesLabel);
+  },
+};
+
+export function withProgress<T>(
+  title: string,
+  task: (report: (p: { message?: string; increment?: number }) => void) => Thenable<T> | T,
+  location: vscode.ProgressLocation = vscode.ProgressLocation.Notification,
+): Thenable<T> {
+  return vscode.window.withProgress({ location, title, cancellable: false }, (progress) =>
+    Promise.resolve(task((p) => progress.report(p))),
+  );
+}

package/templates/_generators/helper/secrets.ts.tpl

@@ -0,0 +1,36 @@
+import * as vscode from 'vscode';
+
+/**
+ * Typed wrapper over `context.secrets` (SecretStorage backed by OS keychain).
+ * Inject the extension context once on activate (bootstrap does this if you
+ * import this module from your extension entry).
+ *
+ * Usage:
+ *   await secrets.set('githubToken', 'ghp_xxx');
+ *   const token = await secrets.get('githubToken');
+ */
+let _ctx: vscode.ExtensionContext | undefined;
+
+export function initSecrets(ctx: vscode.ExtensionContext) {
+  _ctx = ctx;
+}
+
+function ctx(): vscode.ExtensionContext {
+  if (!_ctx) throw new Error('Secrets helper not initialized — call initSecrets(context) on activate.');
+  return _ctx;
+}
+
+export const secrets = {
+  get(key: string): Thenable<string | undefined> {
+    return ctx().secrets.get(key);
+  },
+  set(key: string, value: string): Thenable<void> {
+    return ctx().secrets.store(key, value);
+  },
+  delete(key: string): Thenable<void> {
+    return ctx().secrets.delete(key);
+  },
+  onChange(listener: (key: string) => void): vscode.Disposable {
+    return ctx().secrets.onDidChange((e) => listener(e.key));
+  },
+};

package/templates/_generators/helper/state.ts.tpl

@@ -0,0 +1,44 @@
+import * as vscode from 'vscode';
+
+/**
+ * Typed wrapper over `context.{workspaceState, globalState}`.
+ * - workspace: scoped to the current workspace (per-project preferences)
+ * - global: shared across all workspaces (user-wide settings, last-opened file)
+ *
+ * Usage:
+ *   await state.workspace.set('lastQuery', 'foo');
+ *   const q = state.workspace.get<string>('lastQuery');
+ */
+let _ctx: vscode.ExtensionContext | undefined;
+
+export function initState(ctx: vscode.ExtensionContext) {
+  _ctx = ctx;
+}
+
+function ctx(): vscode.ExtensionContext {
+  if (!_ctx) throw new Error('State helper not initialized — call initState(context) on activate.');
+  return _ctx;
+}
+
+function wrap(memento: () => vscode.Memento) {
+  return {
+    get<T>(key: string, fallback?: T): T | undefined {
+      const v = memento().get<T>(key);
+      return v === undefined ? fallback : v;
+    },
+    set(key: string, value: unknown): Thenable<void> {
+      return memento().update(key, value);
+    },
+    delete(key: string): Thenable<void> {
+      return memento().update(key, undefined);
+    },
+    keys(): readonly string[] {
+      return memento().keys();
+    },
+  };
+}
+
+export const state = {
+  workspace: wrap(() => ctx().workspaceState),
+  global: wrap(() => ctx().globalState),
+};

package/templates/_generators/job/job.ts.tpl

@@ -0,0 +1,10 @@
+import { defineJob } from '../shared/vsceasy';
+
+export default defineJob({
+  title: '{{title}}',
+  schedule: {{schedule}},{{minIntervalLine}}
+  run: async (vscode, ctx) => {
+    // TODO: implement {{name}} work
+    console.log('[{{name}}] tick', new Date().toISOString());
+  },
+});

package/templates/_generators/menu/menu.ts.tpl

@@ -0,0 +1,21 @@
+import { defineMenu } from '../shared/vsceasy';
+
+export default defineMenu({
+  title: '{{title}}',
+  icon: '{{icon}}',
+  items: [
+    {
+      label: 'Panels',
+      children: [
+        // { label: 'Dashboard', panel: 'dashboard' },
+      ],
+    },
+    {
+      label: 'Actions',
+      children: [
+        // { label: 'Hello', command: 'hello', icon: 'play' },
+        // { label: 'Docs', url: 'https://example.com', icon: 'book' },
+      ],
+    },
+  ],
+});

package/templates/_generators/model/model.ts.tpl

@@ -0,0 +1,17 @@
+import { defineEntity, db } from '../helpers/db';
+
+export interface {{Name}} {
+{{fieldLines}}
+}
+
+export const {{Plural}} = defineEntity<{{Name}}>('{{collection}}', {
+  primaryKey: '{{primaryKey}}',{{indexesLine}}
+});
+
+/**
+ * Typed repo accessor. Lazy — assumes `initDb(context)` ran on activate.
+ *
+ *   import { {{Plural}}Repo } from '../models/{{Name}}';
+ *   await {{Plural}}Repo().insert({ ... });
+ */
+export const {{Plural}}Repo = () => db()({{Plural}});

package/templates/_generators/panel/App.tsx.tpl

@@ -0,0 +1,10 @@
+import React from 'react';
+{{apiBlock}}
+export function App() {
+  return (
+    <div className="app">
+      <h1>{{title}}</h1>
+      <p>Edit <code>src/webview/panels/{{name}}/App.tsx</code> to start building.</p>
+    </div>
+  );
+}

package/templates/_generators/panel/main.tsx.tpl

@@ -0,0 +1,6 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { App } from './App';
+import '../../styles.css';
+
+createRoot(document.getElementById('root')!).render(<App />);

package/templates/_generators/panel/panel.ts.tpl

@@ -0,0 +1,5 @@
+import { definePanel } from '../shared/vsceasy';
+{{apiImport}}
+export default definePanel{{apiGeneric}}({
+  title: '{{title}}',{{rpcBlock}}
+});