@ysk-kit/cli 1.0.0

package/dist/upgrade.js

@@ -0,0 +1,110 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { writeAgentStubs } from './agent-stubs';
+export const UPGRADE_PATHS = [
+    'AGENTS.md',
+    'AGENTS.zh.md',
+    'CLAUDE.md',
+    '.dependency-cruiser.cjs',
+    'packages/typescript-config',
+    'packages/biome-config',
+    'docs/skills',
+];
+const SKIP_ENTRIES = new Set(['node_modules', 'dist']);
+export const readKitVersion = (kitRoot) => {
+    const pkg = JSON.parse(readFileSync(join(kitRoot, 'package.json'), 'utf8'));
+    if (!pkg.version)
+        throw new Error('kit package.json has no version');
+    return pkg.version;
+};
+const isProductRoot = (dir) => existsSync(join(dir, '.ysk-kit.json')) ||
+    existsSync(join(dir, 'pnpm-workspace.yaml')) ||
+    existsSync(join(dir, 'AGENTS.md'));
+const readMarker = (productRoot) => {
+    const path = join(productRoot, '.ysk-kit.json');
+    if (!existsSync(path))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new Error('.ysk-kit.json is not valid JSON');
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error('.ysk-kit.json is not valid JSON');
+    }
+    const rec = parsed;
+    return {
+        kit: typeof rec.kit === 'string' ? rec.kit : 'ysk-kit',
+        version: typeof rec.version === 'string' ? rec.version : 'unknown',
+        flavor: typeof rec.flavor === 'string' ? rec.flavor : 'unknown',
+        preset: typeof rec.preset === 'string' ? rec.preset : 'unknown',
+        db: typeof rec.db === 'string' ? rec.db : 'unknown',
+    };
+};
+const copyEntry = (from, to) => {
+    const stat = statSync(from);
+    if (stat.isDirectory()) {
+        mkdirSync(to, { recursive: true });
+        for (const name of readdirSync(from)) {
+            if (SKIP_ENTRIES.has(name))
+                continue;
+            copyEntry(join(from, name), join(to, name));
+        }
+        return;
+    }
+    mkdirSync(dirname(to), { recursive: true });
+    cpSync(from, to);
+};
+export const upgrade = (opts) => {
+    if (!isProductRoot(opts.productRoot)) {
+        throw new Error('run ysk upgrade from a product root, or set YSK_ROOT');
+    }
+    const logs = [];
+    const previous = readMarker(opts.productRoot);
+    const workspaceProduct = existsSync(join(opts.productRoot, 'pnpm-workspace.yaml'));
+    for (const rel of UPGRADE_PATHS) {
+        const from = join(opts.kitRoot, rel);
+        const to = join(opts.productRoot, rel);
+        if (!existsSync(from)) {
+            logs.push(`skip ${rel} (missing in kit)`);
+            continue;
+        }
+        if (!existsSync(to) && !workspaceProduct) {
+            logs.push(`skip ${rel}`);
+            continue;
+        }
+        if (opts.dryRun) {
+            logs.push(`will copy ${rel}`);
+            continue;
+        }
+        copyEntry(from, to);
+        logs.push(`copied ${rel}`);
+    }
+    if (workspaceProduct) {
+        if (opts.dryRun) {
+            logs.push('will write agent stubs');
+        }
+        else {
+            writeAgentStubs(opts.productRoot, opts.kitRoot);
+            logs.push('wrote agent stubs');
+        }
+    }
+    const kitVersion = readKitVersion(opts.kitRoot);
+    const marker = {
+        kit: previous?.kit ?? 'ysk-kit',
+        version: kitVersion,
+        flavor: previous?.flavor ?? 'unknown',
+        preset: previous?.preset ?? 'unknown',
+        db: previous?.db ?? 'unknown',
+    };
+    if (opts.dryRun) {
+        logs.push('will write .ysk-kit.json');
+        return logs;
+    }
+    writeFileSync(join(opts.productRoot, '.ysk-kit.json'), `${JSON.stringify(marker, null, 2)}\n`);
+    logs.push('wrote .ysk-kit.json');
+    return logs;
+};
+//# sourceMappingURL=upgrade.js.map

package/dist/upgrade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../src/upgrade.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ysk-kit/cli",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "ysk": "./dist/index.js"
+  },
+  "dependencies": {
+    "@ysk-kit/api-http": "1.0.0",
+    "@ysk-kit/contracts": "1.0.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "tsx": "^4.19.3",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.2"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run --passWithNoTests",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  }
+}

package/templates/agent/skills/add-capability/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: add-capability
+description: >
+  Merge a catalogued YSK Kit capability (llm, team, billing, push, jobs, mail, …) with ysk add.
+  Use when the user wants ysk add llm/team/billing/push, restore a thin capability, or /add-capability.
+---
+
+Read `docs/skills/add-capability.md`. Law: `AGENTS.md`.

package/templates/agent/skills/add-module/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: add-module
+description: >
+  Add a hexagonal HTTP module with ysk add module (contract, DTO, Express+Fastify, SDK, web page).
+  Use when the user wants a new resource, new API route, ysk add module, or /add-module.
+---
+
+Read `docs/skills/add-module.md`. Law: `AGENTS.md`.

package/templates/agent/skills/envelope-api/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: envelope-api
+description: >
+  Keep YSK Kit JSON routes in {ok,data}/{ok,error}; handle SSE, invoice PDF 302, and OpenAPI exceptions.
+  Use when adding a route, error shape, SSE, PDF, envelope, or /envelope-api.
+---
+
+Read `docs/skills/envelope-api.md`. Law: `AGENTS.md`.

package/templates/agent/skills/fix-layers/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: fix-layers
+description: >
+  Repair a failed pnpm layers / dependency-cruiser run (client imported Prisma, domain imported infra).
+  Use when layers is red, a client imports Express/Prisma, or /fix-layers.
+---
+
+Read `docs/skills/fix-layers.md`. Law: `AGENTS.md`.

package/templates/agent/skills/new-product/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: new-product
+description: >
+  Scaffold a new YSK Kit product with create-ysk-app (thin/full preset, flavors, database).
+  Use when the user wants a new app, new product, create-ysk-app, scaffold, or /new-product.
+---
+
+Read `docs/skills/new-product.md`. Law: `AGENTS.md`.

package/templates/agent/skills/verify-change/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: verify-change
+description: >
+  Verify a YSK Kit change with pnpm layers, typecheck, test, gen:openapi, and ysk check agent.
+  Use when a feature is done, before finishing, after a module, or /verify-change.
+---
+
+Read `docs/skills/verify-change.md`. Law: `AGENTS.md`.

package/templates/agent/ysk-kit.mdc

@@ -0,0 +1,6 @@
+---
+description: YSK Kit agent law — contracts, envelope, layers
+alwaysApply: true
+---
+
+Follow `AGENTS.md` at the repo root before writing code (Chinese: `AGENTS.zh.md`). Procedures live in `docs/skills/`. New HTTP features start with `pnpm ysk add module <kebab-name> --prisma --web`. Do not invent TypeScript enums, import Prisma from clients, or return JSON outside `{ ok, data }` / `{ ok, error }`. Run `pnpm layers && pnpm typecheck && pnpm test && pnpm gen:openapi` before finishing.

package/templates/capabilities/billing/apps/api/src/modules/billing/application/billing-service.ts

@@ -0,0 +1,140 @@
+import type { CheckoutCommand, SubscriptionDto } from '@ysk-kit/contracts';
+import { BILLING_PLANS, orgRoleCan } from '@ysk-kit/contracts';
+import { AppError } from '@ysk-kit/domain-kernel';
+import type { IOrganizationRepository } from '../../organizations/domain/organization-repository';
+import type { IBillingPort } from '../domain/billing-port';
+import type { ISubscriptionRepository } from '../domain/subscription-repository';
+
+const PERIOD_MS = 1000 * 60 * 60 * 24 * 30;
+
+const freeSub = (): SubscriptionDto => ({
+  planCode: 'free',
+  status: 'active',
+  currentPeriodEnd: null,
+  seatCount: 1,
+});
+
+const toDto = (row: {
+  planCode: SubscriptionDto['planCode'];
+  status: SubscriptionDto['status'];
+  currentPeriodEnd: Date | null;
+  seatCount: number;
+}): SubscriptionDto => ({
+  planCode: row.planCode,
+  status: row.status,
+  currentPeriodEnd: row.currentPeriodEnd ? row.currentPeriodEnd.toISOString() : null,
+  seatCount: row.seatCount,
+});
+
+export const createBillingService = (opts: {
+  subscriptions: ISubscriptionRepository;
+  billing: IBillingPort;
+  orgs: IOrganizationRepository;
+  now?: () => Date;
+}) => {
+  const now = () => opts.now?.() ?? new Date();
+
+  const requireBiller = async (userId: string, organizationId: string) => {
+    const org = await opts.orgs.findById(organizationId);
+    if (!org) throw new AppError('NOT_FOUND');
+    const membership = await opts.orgs.findMembership(organizationId, userId);
+    if (!membership || !orgRoleCan(membership.role, 'org.billing')) {
+      throw new AppError('FORBIDDEN');
+    }
+    return org;
+  };
+
+  return {
+    plans: () => BILLING_PLANS,
+    subscription: async (userId: string, organizationId: string): Promise<SubscriptionDto> => {
+      await requireBiller(userId, organizationId);
+      const row = await opts.subscriptions.findByOrganizationId(organizationId);
+      return row ? toDto(row) : freeSub();
+    },
+    invoices: async (userId: string, organizationId: string) => {
+      const org = await requireBiller(userId, organizationId);
+      if (!org.stripeCustomerId) return [];
+      return opts.billing.listInvoices({ customerId: org.stripeCustomerId });
+    },
+    invoicePdf: async (userId: string, organizationId: string, invoiceId: string) => {
+      const org = await requireBiller(userId, organizationId);
+      if (!org.stripeCustomerId) return null;
+      return opts.billing.getInvoicePdf({
+        customerId: org.stripeCustomerId,
+        invoiceId,
+      });
+    },
+    activate: async (
+      organizationId: string,
+      planCode: SubscriptionDto['planCode'],
+      customerId?: string,
+      seatCount = 1,
+    ) => {
+      if (planCode === 'free') return;
+      const org = await opts.orgs.findById(organizationId);
+      if (!org) throw new AppError('NOT_FOUND');
+      await opts.subscriptions.upsert({
+        organizationId,
+        planCode,
+        status: 'active',
+        currentPeriodEnd: new Date(now().getTime() + PERIOD_MS),
+        seatCount,
+      });
+      if (customerId) await opts.orgs.setStripeCustomerId(organizationId, customerId);
+    },
+    portal: async (userId: string, organizationId: string, returnUrl: string) => {
+      const org = await requireBiller(userId, organizationId);
+      const customerId = org.stripeCustomerId;
+      if (opts.billing.requiresCustomer && !customerId) {
+        throw new AppError('CONFLICT', 'Complete checkout first');
+      }
+      return opts.billing.portal({
+        returnUrl,
+        customerId: customerId ?? 'cus_stub',
+      });
+    },
+    checkout: async (userId: string, body: CheckoutCommand) => {
+      if (body.planCode === 'free') throw new AppError('VALIDATION_FAILED', 'Cannot checkout free');
+      await requireBiller(userId, body.organizationId);
+      const members = await opts.orgs.listMembers(body.organizationId);
+      if (body.seatCount < members.length) {
+        throw new AppError('VALIDATION_FAILED', 'seatCount below member count');
+      }
+      const org = await opts.orgs.findById(body.organizationId);
+      const result = await opts.billing.checkout({
+        organizationId: body.organizationId,
+        planCode: body.planCode,
+        successUrl: body.successUrl,
+        cancelUrl: body.cancelUrl,
+        seatCount: body.seatCount,
+        ...(org?.stripeCustomerId ? { customerId: org.stripeCustomerId } : {}),
+      });
+      if (!result.pending) {
+        await opts.subscriptions.upsert({
+          organizationId: body.organizationId,
+          planCode: body.planCode,
+          status: 'active',
+          currentPeriodEnd: new Date(now().getTime() + PERIOD_MS),
+          seatCount: body.seatCount,
+        });
+      }
+      return { url: result.url };
+    },
+    cancel: async (userId: string, organizationId: string) => {
+      await requireBiller(userId, organizationId);
+      const row = await opts.subscriptions.findByOrganizationId(organizationId);
+      if (row) {
+        await opts.subscriptions.upsert({
+          organizationId,
+          planCode: row.planCode,
+          status: 'canceled',
+          currentPeriodEnd: row.currentPeriodEnd,
+          seatCount: row.seatCount,
+        });
+      }
+      return { canceled: true as const };
+    },
+  };
+};
+
+export type BillingService = ReturnType<typeof createBillingService>;

package/templates/capabilities/billing/apps/api/src/modules/billing/domain/billing-port.ts

@@ -0,0 +1,23 @@
+export type CheckoutInput = {
+  organizationId: string;
+  planCode: string;
+  successUrl: string;
+  cancelUrl: string;
+  seatCount: number;
+  customerId?: string;
+};
+
+export type CheckoutResult = {
+  url: string;
+  pending?: true;
+};
+
+import type { InvoiceDto } from '@ysk-kit/contracts';
+
+export interface IBillingPort {
+  checkout(input: CheckoutInput): Promise<CheckoutResult>;
+  portal(input: { returnUrl: string; customerId: string }): Promise<{ url: string }>;
+  listInvoices(input: { customerId: string }): Promise<InvoiceDto[]>;
+  getInvoicePdf(input: { customerId: string; invoiceId: string }): Promise<{ url: string } | null>;
+  requiresCustomer?: true;
+}

package/templates/capabilities/billing/apps/api/src/modules/billing/domain/subscription-repository.ts

@@ -0,0 +1,22 @@
+import type { BillingPlanCode, SubscriptionStatus } from '@ysk-kit/contracts';
+
+export type SubscriptionRecord = {
+  id: string;
+  organizationId: string;
+  planCode: BillingPlanCode;
+  status: SubscriptionStatus;
+  currentPeriodEnd: Date | null;
+  seatCount: number;
+  createdAt: Date;
+};
+
+export interface ISubscriptionRepository {
+  findByOrganizationId(organizationId: string): Promise<SubscriptionRecord | null>;
+  upsert(input: {
+    organizationId: string;
+    planCode: BillingPlanCode;
+    status: SubscriptionStatus;
+    currentPeriodEnd: Date | null;
+    seatCount: number;
+  }): Promise<SubscriptionRecord>;
+}

package/templates/capabilities/billing/apps/api/src/modules/billing/infra/billing-router.ts

@@ -0,0 +1,85 @@
+import { type HttpHandler, mountContract } from '@ysk-kit/api-express';
+import {
+  appContract,
+  type CancelCommand,
+  type CheckoutCommand,
+  type OrganizationIdQuery,
+  type PortalCommand,
+} from '@ysk-kit/contracts';
+import { AppError } from '@ysk-kit/domain-kernel';
+import type { Express } from 'express';
+import type { BillingService } from '../application/billing-service';
+
+const orgQuery = (query: unknown): string => (query as OrganizationIdQuery).organizationId;
+
+export const billingHandlers = (service: BillingService): Record<string, HttpHandler> => ({
+  plans: {
+    handle: async () => ({ status: 200, body: { ok: true, data: service.plans() } }),
+  },
+  subscription: {
+    auth: 'required',
+    permission: 'billing.checkout',
+    handle: async ({ auth, query }) => {
+      if (!auth) throw new AppError('UNAUTHENTICATED');
+      return {
+        status: 200,
+        body: { ok: true, data: await service.subscription(auth.sub, orgQuery(query)) },
+      };
+    },
+  },
+  invoices: {
+    auth: 'required',
+    permission: 'billing.checkout',
+    handle: async ({ auth, query }) => {
+      if (!auth) throw new AppError('UNAUTHENTICATED');
+      return {
+        status: 200,
+        body: { ok: true, data: await service.invoices(auth.sub, orgQuery(query)) },
+      };
+    },
+  },
+  checkout: {
+    auth: 'required',
+    permission: 'billing.checkout',
+    handle: async ({ body, auth }) => {
+      if (!auth) throw new AppError('UNAUTHENTICATED');
+      return {
+        status: 200,
+        body: { ok: true, data: await service.checkout(auth.sub, body as CheckoutCommand) },
+      };
+    },
+  },
+  cancel: {
+    auth: 'required',
+    permission: 'billing.checkout',
+    handle: async ({ auth, body }) => {
+      if (!auth) throw new AppError('UNAUTHENTICATED');
+      return {
+        status: 200,
+        body: {
+          ok: true,
+          data: await service.cancel(auth.sub, (body as CancelCommand).organizationId),
+        },
+      };
+    },
+  },
+  portal: {
+    auth: 'required',
+    permission: 'billing.checkout',
+    handle: async ({ body, auth }) => {
+      if (!auth) throw new AppError('UNAUTHENTICATED');
+      const command = body as PortalCommand;
+      return {
+        status: 200,
+        body: {
+          ok: true,
+          data: await service.portal(auth.sub, command.organizationId, command.returnUrl),
+        },
+      };
+    },
+  },
+});
+
+export const registerBillingRoutes = (app: Express, service: BillingService): void => {
+  mountContract(app, appContract.billing, billingHandlers(service));
+};