@cicore/cli 1.0.0

package/dist/lib/ops/addon-quality.js

@@ -0,0 +1,338 @@
+/**
+ * Quality stack templates shared by `ci addon create` (new addons) and
+ * `ci addon scaffold-quality` (existing addon backport — Faz 5B).
+ *
+ * Tooling binaries (eslint, vue-tsc, prettier) live in dev-shell's
+ * top-level node_modules so a single `npm install` covers every addon
+ * on the machine — the configs here just point each addon's source
+ * files at the shared toolchain.
+ *
+ * Legacy .eslintrc.json instead of flat config: ESLint 9's flat config
+ * requires a JS module file in every addon (with explicit plugin
+ * imports). The legacy JSON form works fine in ESLint 8.x and stays
+ * personnel-friendly. We'll switch when the Vue + TypeScript plugin
+ * ecosystem catches up to flat config.
+ */
+export function genEslintConfig() {
+    return {
+        root: true,
+        env: { browser: true, es2022: true, node: true },
+        parser: 'vue-eslint-parser',
+        parserOptions: {
+            parser: '@typescript-eslint/parser',
+            ecmaVersion: 'latest',
+            sourceType: 'module',
+            extraFileExtensions: ['.vue'],
+        },
+        plugins: ['vue', '@typescript-eslint'],
+        extends: [
+            'eslint:recommended',
+            'plugin:vue/vue3-recommended',
+            'plugin:@typescript-eslint/recommended',
+        ],
+        rules: {
+            // Single-word component names are common in addon page files
+            // (index.vue, list.vue). Vue's default rule would force PascalCase
+            // multi-word; ergonomically wrong for our routing layout.
+            'vue/multi-word-component-names': 'off',
+            'vue/html-self-closing': ['error', { html: { void: 'always', normal: 'always', component: 'always' } }],
+            // any-warnings rather than errors so addon authors can ship a TODO
+            // explicitly; the warning surfaces in the deploy quality gate.
+            '@typescript-eslint/no-explicit-any': 'warn',
+            'no-unused-vars': 'off',
+            '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+            'prefer-const': 'error',
+            'no-var': 'error',
+        },
+        ignorePatterns: ['dist/', 'node_modules/', '.vite-cache/', '*.d.ts', 'empty-devtools.js'],
+    };
+}
+export function genPrettierConfig() {
+    return {
+        semi: false,
+        singleQuote: true,
+        tabWidth: 2,
+        printWidth: 100,
+        trailingComma: 'es5',
+        vueIndentScriptAndStyle: false,
+        endOfLine: 'lf',
+    };
+}
+export function genEditorConfig() {
+    return `root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+`;
+}
+export function genTsConfig() {
+    return {
+        compilerOptions: {
+            target: 'ES2022',
+            module: 'ESNext',
+            moduleResolution: 'Bundler',
+            // Lenient by default — addon authors are mostly writing Vue SFC
+            // glue code over @cicore/shared composables, not isolated TS
+            // libraries. Forcing strict mode out of the box would block deploys
+            // on every implicit-any parameter (callback args, event handlers,
+            // template refs). Personnel who want stronger guarantees can flip
+            // strict: true once their addon's @cicore/shared usage stabilises;
+            // the FUTURE typed SDK will let us re-enable globally.
+            strict: false,
+            noImplicitAny: false,
+            esModuleInterop: true,
+            skipLibCheck: true,
+            isolatedModules: true,
+            resolveJsonModule: true,
+            noEmit: true,
+            jsx: 'preserve',
+            lib: ['ES2022', 'DOM', 'DOM.Iterable'],
+            // vue types resolved from dev-shell/node_modules/vue (parent
+            // lookup) so the addon doesn't need its own node_modules.
+            types: ['vue'],
+            paths: {
+                '@/*': ['./*'],
+            },
+        },
+        include: ['**/*.ts', '**/*.vue', 'ui/entry.ts'],
+        exclude: ['node_modules', 'dist', '.vite-cache'],
+    };
+}
+/**
+ * Ambient type declarations for the addon source. The runtime resolves
+ * `@cicore/shared` via the host's import map and `$fetch` is Nuxt's
+ * global, but vue-tsc has no way to find either without these shims.
+ * Declared as `any` for now — Faz 6 (SDK docs) ships richer type
+ * surfaces alongside the API reference and replaces these stubs.
+ */
+export function genAmbientTypes() {
+    return `// Ambient types for ciCore addon runtime. Replaced by the real
+// @cicore/shared types when the SDK package ships (Faz 6 FUTURE).
+
+declare module '@cicore/shared' {
+  // Runtime exports come from the host's import map — every Vue Composition
+  // API name, the useApi/useAuth/useI18n composables, and the Nuxt UI
+  // components are re-exported here. Typed as generic any-functions so
+  // calls like \`useApi<MyType>()\` and \`ref<MyType>(initial)\` work without
+  // raising TS error 2347 (Untyped function calls may not accept type
+  // arguments). Faz 6 (SDK docs) replaces these stubs with typed surfaces.
+  //
+  // NOTE: TypeScript doesn't have a "catch-all named exports" syntax, so
+  // every name an addon imports must appear here. If vue-tsc rejects an
+  // import you need, add it to this list (and to docs/addon-sdk in Faz 6).
+
+  // Generic any-callable — accepts type args, accepts any positional args,
+  // returns any. Permissive but lets vue-tsc see something callable.
+  type AnyFn = <T = any, R = any>(...args: any[]) => any
+
+  // Vue Composition API surface (re-exported by @cicore/shared)
+  export const ref: AnyFn
+  export const reactive: AnyFn
+  export const computed: AnyFn
+  export const watch: AnyFn
+  export const watchEffect: AnyFn
+  export const onMounted: AnyFn
+  export const onUnmounted: AnyFn
+  export const onBeforeMount: AnyFn
+  export const onBeforeUnmount: AnyFn
+  export const nextTick: AnyFn
+  export const defineComponent: AnyFn
+  export const defineProps: AnyFn
+  export const defineEmits: AnyFn
+
+  // ciCore platform composables
+  export const useI18n: AnyFn
+  export const useAuth: AnyFn
+  export const useApi: AnyFn
+  export const useAddons: AnyFn
+  export const useTenant: AnyFn
+  export const usePermissions: AnyFn
+  export const useIcon: AnyFn
+  export const useNuxtUI: AnyFn
+  export const useRuntimeConfig: AnyFn
+  export const useToast: AnyFn
+  export const useRouter: AnyFn
+  export const useRoute: AnyFn
+  export const useGsap: AnyFn
+
+  // Nuxt UI components — opaque to TS (real types in Faz 6)
+  export const Icon: any
+  export const UButton: any
+  export const UCard: any
+  export const UInput: any
+  export const UInputMenu: any
+  export const UModal: any
+  export const USelectMenu: any
+  export const USwitch: any
+  export const UAlert: any
+  export const UBadge: any
+  export const UTooltip: any
+  export const UFieldGroup: any
+  export const UForm: any
+  export const UFormField: any
+  export const UTextarea: any
+  export const UCheckbox: any
+  export const UTable: any
+  export const UPagination: any
+  export const UAvatar: any
+  export const UDropdownMenu: any
+
+  const _default: any
+  export default _default
+}
+
+// Nuxt global available to addon pages without explicit import.
+declare const $fetch: <T = unknown>(url: string, opts?: Record<string, unknown>) => Promise<T>
+
+// Vue SFC module shim so .vue imports resolve to a component type.
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
+  export default component
+}
+`;
+}
+export function genGitlabCi(addonName) {
+    return `# Auto-generated by \`ci addon create ${addonName}\`. FAZ-3 git-workflow template.
+#
+# Pipeline: check (every push/MR) → build (every commit/MR/tag) → publish (tag + PUBLISH_TRIGGER)
+#
+# CI/CD variables — cicore-addons group #63'te tanımlı olmalı:
+#   Mevcut : CICORE_CLOUDFLARE_ZONE_ID, CICORE_CLOUDFLARE_API_TOKEN, CICORE_CDN_BASE_URL
+#   Ekle   : CDN_GRANT_SECRET    (HMAC-imza, publish.ts:L92)
+#            CICORE_CDN_API_KEY  (CDN Gateway API key — Kasa vault: ci kasa get cicore cdn-api-key)
+#            CICORE_SSH_KEY      (file — runner→cicore-host, enqueue için)
+#            CICORE_SSH_HOST     (cicore deploy host IP/adı)
+#            CICORE_SSH_USER     (deploy SSH kullanıcısı)
+
+stages:
+  - check
+  - build
+  - publish
+
+# ── Stage 1: Kalite kontrolü (her push + MR) ─────────────────────────────────
+# KARAR-1 (erhan): Addon kendi devDeps kullanır — dev-shell coupling yok.
+quality:
+  stage: check
+  image: node:22-alpine
+  cache:
+    key: \${CI_PROJECT_NAME}-node_modules
+    paths: [node_modules/]
+  script:
+    - npm ci --no-audit --no-fund
+    - npx eslint . --max-warnings 0
+    - npx vue-tsc --noEmit
+  allow_failure: false
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+# ── Stage 2: Frontend build (her commit + MR + tag) ──────────────────────────
+# KARAR-1 (erhan): Addon kendi devDeps kullanır — dev-shell coupling yok, sürüm kayması önlenir.
+build:
+  stage: build
+  image: node:22-alpine
+  cache:
+    key: \${CI_PROJECT_NAME}-node_modules
+    paths: [node_modules/]
+  script:
+    - npm ci --no-audit --no-fund
+    - npm run build
+    - test -f dist/entry.js || (echo "❌ dist/entry.js not found" && exit 1)
+  artifacts:
+    paths:
+      - dist/
+    expire_in: 1 hour
+  allow_failure: false
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH
+    - if: $CI_COMMIT_TAG
+
+# ── Stage 3: Publish — 8-adım (main branch + tag, build başarılıysa) ─────────
+# Erhan mimari onaylı sıra (publish.ts akışını yansıtır):
+#   Adım 1: Vite build → dist/         (build stage artifact)
+#   Adım 2: SAST (Semgrep)             fail-closed
+#   Adım 3: Package                    Backend/ → pkg.tar.gz  +  dist/ → fe.zip
+#   Adım 4: SHA256 + HMAC-sign         CDN_GRANT_SECRET ile (publish.ts:L92)
+#   Adım 5: Frontend → R2              CDN Gateway /upload-coreui-zip
+#   Adım 6: Backend pkg.tar.gz → R2    CDN Worker (zip wrapper)
+#   Adım 7: CF cache purge             CICORE_CLOUDFLARE_ZONE_ID
+#   Adım 8: SSH enqueue                cp_provisioning_jobs → AddonRegistryService
+publish:
+  stage: publish
+  image: node:22-alpine
+  needs: [build]
+  before_script:
+    - apk add --no-cache openssh-client git
+    # CLI: VPN içi GitLab'dan git clone (npmjs publish beklenmez)
+    # CI/CD variable: CICORE_CLI_REPO (örn. http://10.20.20.28/cicore/cli.git)
+    #                 GITLAB_TOKEN    (okuma yetkili PAT, group #63'te tanımlı)
+    - git clone --depth 1 "http://oauth2:$\{GITLAB_TOKEN}@$\{CICORE_CLI_REPO#http://}" /tmp/cicore-cli
+    - cd /tmp/cicore-cli && npm ci --no-audit --no-fund --prefer-offline
+    - export PATH="$PATH:/tmp/cicore-cli/bin"
+    - cd "$CI_PROJECT_DIR"
+    # SSH key kurulumu (Adım 8: enqueue)
+    - mkdir -p ~/.ssh && chmod 700 ~/.ssh
+    - echo "$CICORE_SSH_KEY" > ~/.ssh/id_deploy && chmod 600 ~/.ssh/id_deploy
+    - ssh-keyscan -H "$CICORE_SSH_HOST" >> ~/.ssh/known_hosts 2>/dev/null
+  script:
+    # CI/CD variables (cicore-addons group #63'te tanımlı olmalı):
+    #   CDN_GRANT_SECRET         — HMAC-imza (publish.ts)
+    #   CICORE_CDN_API_KEY       — CDN Gateway API key
+    #   CICORE_CDN_BASE_URL      — CDN base URL
+    #   CICORE_CLOUDFLARE_API_TOKEN
+    #   CICORE_CLOUDFLARE_ZONE_ID
+    #   CICORE_SSH_HOST + CICORE_SSH_USER + CICORE_SSH_KEY
+    #   CICORE_CLI_REPO          — http://10.20.20.28/cicore/cli.git
+    #   GITLAB_TOKEN             — okuma PAT
+    - VERSION=$(node -p "require('./addon.json').version")
+    - echo "Publishing ${addonName} v$VERSION..."
+    - ci addon publish ${addonName} --version "$VERSION" --requested-by ci
+  environment:
+    name: marketplace
+  allow_failure: false
+  rules:
+    - if: $CI_COMMIT_TAG
+    - if: $PUBLISH_TRIGGER
+`;
+}
+export async function applyQualityTemplate(addonDir, addonName, options = {}) {
+    const fs = await import('fs-extra');
+    const path = await import('node:path');
+    const files = [
+        { rel: '.eslintrc.json', content: genEslintConfig() },
+        { rel: '.prettierrc.json', content: genPrettierConfig() },
+        { rel: '.editorconfig', content: genEditorConfig() },
+        { rel: 'tsconfig.json', content: genTsConfig() },
+        { rel: '.gitlab-ci.yml', content: genGitlabCi(addonName) },
+        { rel: 'env.d.ts', content: genAmbientTypes() },
+    ];
+    const written = [];
+    const skipped = [];
+    for (const { rel, content } of files) {
+        const target = path.join(addonDir, rel);
+        if (!options.overwrite && (await fs.default.pathExists(target))) {
+            skipped.push(rel);
+            continue;
+        }
+        await fs.default.ensureDir(path.dirname(target));
+        if (typeof content === 'object') {
+            await fs.default.writeJson(target, content, { spaces: 2 });
+        }
+        else {
+            await fs.default.writeFile(target, content, 'utf8');
+        }
+        written.push(rel);
+    }
+    return { written, skipped };
+}
+//# sourceMappingURL=addon-quality.js.map

package/dist/lib/ops/addon-quality.js.map

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

package/dist/lib/ops/addon-routes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Dynamic nginx PHP routes regex generation.
+ *
+ * The PHP location block in dev.conf used to be a hand-maintained
+ * alternation of ~30 path prefixes — every new addon required the
+ * developer to read its Backend/Routes/*.php files, eyeball the
+ * `$app->get('/<prefix>/...')` calls, and append the prefix to the
+ * regex. A miss surfaced as Nuxt 404'ing API requests until the regex
+ * was patched. The old comment in dev.conf even documented this as a
+ * known gotcha: "When you `ci addon dev-deploy` a new addon, eyeball
+ * its `$app->get('/<prefix>/...')` and `$app->group('/<prefix>')`
+ * calls and add the missing token to this alternation."
+ *
+ * This module scans every active addon's route files, extracts the
+ * first path segment of each registered route, merges it with a
+ * baseline list of core PHP routes, and renders an nginx location
+ * snippet. `ci addon dev`, `ci cache flush`, and `init.sh` all call
+ * `regeneratePhpRoutes()` so personnel never edits the regex by hand.
+ *
+ * Output lives at `nginx/snippets/00-php-routes.conf` (gitignored; CLI-
+ * owned). The `00-` prefix orders it before the per-addon HMR snippets
+ * in the include glob.
+ */
+/**
+ * Scan every addon's Backend/Routes/*.php under the dev tenant and
+ * return the set of first-path-segments (sorted, unique). Run from
+ * the dev-shell root; absolute paths are derived from there.
+ */
+export declare function scanAddonPrefixes(shellRoot: string): Promise<string[]>;
+/** Compose the full alternation list (core + addon prefixes, deduped). */
+export declare function buildPhpRoutesRegex(addonPrefixes: string[]): string;
+/** Render the full nginx location block. The CORS + fastcgi config
+ *  mirrors what dev.conf used to inline — keeping it in the snippet so
+ *  the static dev.conf can drop the whole block. */
+export declare function buildPhpRoutesSnippet(addonPrefixes: string[]): string;
+/**
+ * High-level entry point used by `ci addon dev`, `ci cache flush`, and
+ * init.sh. Scans, renders, writes, reloads (best-effort). Returns the
+ * full result so callers can log meaningfully.
+ */
+export declare function regeneratePhpRoutes(shellRoot: string): Promise<{
+    prefixesAdded: string[];
+    totalPrefixes: number;
+    reload: {
+        method: 'reload' | 'startup' | 'failed';
+        detail: string;
+    };
+}>;
+//# sourceMappingURL=addon-routes.d.ts.map

package/dist/lib/ops/addon-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addon-routes.d.ts","sourceRoot":"","sources":["../../../src/lib/ops/addon-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA2CH;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAmB5E;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,CAOnE;AAED;;oDAEoD;AACpD,wBAAgB,qBAAqB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,CA0CrE;AAgCD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACpE,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE;QAAE,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CACpE,CAAC,CAcD"}

package/dist/lib/ops/addon-routes.js

@@ -0,0 +1,189 @@
+/**
+ * Dynamic nginx PHP routes regex generation.
+ *
+ * The PHP location block in dev.conf used to be a hand-maintained
+ * alternation of ~30 path prefixes — every new addon required the
+ * developer to read its Backend/Routes/*.php files, eyeball the
+ * `$app->get('/<prefix>/...')` calls, and append the prefix to the
+ * regex. A miss surfaced as Nuxt 404'ing API requests until the regex
+ * was patched. The old comment in dev.conf even documented this as a
+ * known gotcha: "When you `ci addon dev-deploy` a new addon, eyeball
+ * its `$app->get('/<prefix>/...')` and `$app->group('/<prefix>')`
+ * calls and add the missing token to this alternation."
+ *
+ * This module scans every active addon's route files, extracts the
+ * first path segment of each registered route, merges it with a
+ * baseline list of core PHP routes, and renders an nginx location
+ * snippet. `ci addon dev`, `ci cache flush`, and `init.sh` all call
+ * `regeneratePhpRoutes()` so personnel never edits the regex by hand.
+ *
+ * Output lives at `nginx/snippets/00-php-routes.conf` (gitignored; CLI-
+ * owned). The `00-` prefix orders it before the per-addon HMR snippets
+ * in the include glob.
+ */
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import fs from 'fs-extra';
+import { glob } from 'glob';
+// Core PHP route prefixes that the platform always reserves. Mirrors
+// the previous static list in dev.conf. `core(?!s)` is the negative
+// lookahead Faz 1 POC introduced — without it the token matches
+// `cores/<x>/shared/` and shoves static paths into PHP-FPM.
+const CORE_PHP_PREFIXES = [
+    'api', 'v1', 'v2', 'auth', 'system', 'system-settings', 'upload',
+    'addons', 'core_addons', 'core(?!s)', 'analyzer', 'summary',
+    'metrics', 'jobs', 'worker', 'setup', 'tenant-manager',
+    'tenant-admin', 'user-admin', 'users', 'csrf-token', 'refresh',
+    'languages', 'institutions', 'sectors', 'security', 'odeme',
+    'builds', 'catalog', 'web-index', 'login', 'logout', 'me',
+    'public', 'status',
+];
+// First-path-segment extractor for Slim routes. Captures both the
+// shorthand methods (`$app->get('/foo/...', ...)`) and group prefix
+// (`$app->group('/foo', ...)`). Surrounding whitespace is permissive
+// so reformatted route files don't slip through.
+const ROUTE_REGEX = /\$app->(?:get|post|put|delete|patch|group)\s*\(\s*['"]\/([a-zA-Z][a-zA-Z0-9_-]*)/g;
+const SNIPPET_REL_PATH = 'nginx/snippets/00-php-routes.conf';
+const NGINX_CONTAINER = 'addon_dev_nginx';
+const SNIPPET_HEADER = `# AUTO-GENERATED by \`ci addon routes regenerate\`. Do not edit by hand.
+# Sourced from cores/dev/addons/*/Backend/Routes/*.php — every new addon's
+# first-path-segment is added automatically. The regex alternation is the
+# load-bearing piece: nginx routes any URL matching ^/<token>(/|EOL|...)
+# to PHP-FPM. Tokens NOT in this list fall through to the catch-all
+# location (Nuxt SSR) — that's how /admin/* etc. reaches the front-end.
+#
+# To force a regenerate after editing addon routes:
+#   ci addon routes regenerate          # (Faz 4.3 — coming)
+# Or, currently:
+#   ci cache flush                      # also rebuilds this file
+`;
+/**
+ * Scan every addon's Backend/Routes/*.php under the dev tenant and
+ * return the set of first-path-segments (sorted, unique). Run from
+ * the dev-shell root; absolute paths are derived from there.
+ */
+export async function scanAddonPrefixes(shellRoot) {
+    const phpFiles = await glob('cores/dev/addons/*/Backend/Routes/*.php', { cwd: shellRoot, absolute: true });
+    const prefixes = new Set();
+    for (const file of phpFiles) {
+        let content;
+        try {
+            content = await fs.readFile(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        // Reset lastIndex because the regex is shared across iterations
+        // (JS global regexes are stateful).
+        ROUTE_REGEX.lastIndex = 0;
+        let match;
+        while ((match = ROUTE_REGEX.exec(content)) !== null) {
+            prefixes.add(match[1]);
+        }
+    }
+    return [...prefixes].sort();
+}
+/** Compose the full alternation list (core + addon prefixes, deduped). */
+export function buildPhpRoutesRegex(addonPrefixes) {
+    // Strip the `(?!s)` decoration when checking for duplicates against
+    // the addon list — an addon called "core" would otherwise sneak past
+    // the de-dup because `core(?!s)` !== `core` as strings.
+    const coreTokens = new Set(CORE_PHP_PREFIXES.map((t) => t.replace(/\(\?!.*?\)$/, '')));
+    const additions = addonPrefixes.filter((p) => !coreTokens.has(p));
+    return [...CORE_PHP_PREFIXES, ...additions].join('|');
+}
+/** Render the full nginx location block. The CORS + fastcgi config
+ *  mirrors what dev.conf used to inline — keeping it in the snippet so
+ *  the static dev.conf can drop the whole block. */
+export function buildPhpRoutesSnippet(addonPrefixes) {
+    const regex = buildPhpRoutesRegex(addonPrefixes);
+    return `${SNIPPET_HEADER}
+location ~ ^/(${regex}) {
+    # CORS preflight (browser fetch from http://localhost:3000 hits 3080)
+    if ($request_method = 'OPTIONS') {
+        add_header 'Access-Control-Allow-Origin' $http_origin always;
+        add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, PATCH, DELETE, OPTIONS' always;
+        add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, X-Requested-With, X-CSRF-Token, X-Core-Path, X-Tenant-Host, Cache-Control, Accept' always;
+        add_header 'Access-Control-Allow-Credentials' 'true' always;
+        add_header 'Access-Control-Max-Age' '86400' always;
+        add_header 'Content-Type' 'text/plain; charset=utf-8' always;
+        add_header 'Content-Length' '0' always;
+        return 204;
+    }
+
+    add_header 'Access-Control-Allow-Origin' $http_origin always;
+    add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, PATCH, DELETE, OPTIONS' always;
+    add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, X-Requested-With, X-CSRF-Token, X-Core-Path, X-Tenant-Host, Accept' always;
+    add_header 'Access-Control-Allow-Credentials' 'true' always;
+    add_header 'Access-Control-Expose-Headers' 'X-CSRF-Token' always;
+
+    fastcgi_pass addon_dev_php:9000;
+    fastcgi_param SCRIPT_FILENAME /var/www/public/index.php;
+    fastcgi_param CORE_PATH /var/www/cores/dev;
+    include fastcgi_params;
+    fastcgi_param REQUEST_URI $request_uri;
+    fastcgi_param SCRIPT_NAME /index.php;
+    fastcgi_param HTTP_HOST $host;
+    fastcgi_param HTTP_TENANT_HOST $host;
+    # Dev: HTTP (production'da HTTPS on, X-Forwarded-Proto https)
+    fastcgi_param HTTP_X_FORWARDED_PROTO http;
+
+    fastcgi_connect_timeout 300s;
+    fastcgi_send_timeout 300s;
+    fastcgi_read_timeout 300s;
+    fastcgi_buffer_size 128k;
+    fastcgi_buffers 4 256k;
+    fastcgi_busy_buffers_size 256k;
+    fastcgi_temp_file_write_size 256k;
+}
+`;
+}
+/** Atomic write via tmp+rename so a kill mid-write doesn't truncate
+ *  the snippet. */
+async function writeSnippet(shellRoot, content) {
+    const filePath = path.join(shellRoot, SNIPPET_REL_PATH);
+    await fs.ensureDir(path.dirname(filePath));
+    const tmp = `${filePath}.tmp.${process.pid}`;
+    await fs.writeFile(tmp, content, 'utf8');
+    await fs.move(tmp, filePath, { overwrite: true });
+}
+/** Try `docker exec nginx -t && nginx -s reload`. Skip cleanly when the
+ *  container isn't running — init.sh's first pass writes the snippet
+ *  before `docker compose up -d` and that's fine; nginx will pick the
+ *  file up at startup. */
+async function reloadNginxIfRunning() {
+    const ps = spawnSync('docker', ['ps', '--filter', `name=${NGINX_CONTAINER}`, '--filter', 'status=running', '--format', '{{.Names}}'], { encoding: 'utf8' });
+    if (ps.status !== 0 || !String(ps.stdout || '').includes(NGINX_CONTAINER)) {
+        return { method: 'startup', detail: `${NGINX_CONTAINER} not running — snippet picked up on next start` };
+    }
+    const test = spawnSync('docker', ['exec', NGINX_CONTAINER, 'nginx', '-t'], { encoding: 'utf8' });
+    if (test.status !== 0) {
+        return { method: 'failed', detail: String(test.stderr || test.stdout || '').trim() };
+    }
+    const reload = spawnSync('docker', ['exec', NGINX_CONTAINER, 'nginx', '-s', 'reload'], { encoding: 'utf8' });
+    if (reload.status !== 0) {
+        return { method: 'failed', detail: String(reload.stderr || reload.stdout || '').trim() };
+    }
+    return { method: 'reload', detail: 'nginx -s reload OK' };
+}
+/**
+ * High-level entry point used by `ci addon dev`, `ci cache flush`, and
+ * init.sh. Scans, renders, writes, reloads (best-effort). Returns the
+ * full result so callers can log meaningfully.
+ */
+export async function regeneratePhpRoutes(shellRoot) {
+    const addonPrefixes = await scanAddonPrefixes(shellRoot);
+    // Distinguish "added by addons" from baseline — only the additions
+    // are interesting to log.
+    const coreTokens = new Set(CORE_PHP_PREFIXES.map((t) => t.replace(/\(\?!.*?\)$/, '')));
+    const prefixesAdded = addonPrefixes.filter((p) => !coreTokens.has(p));
+    const content = buildPhpRoutesSnippet(addonPrefixes);
+    await writeSnippet(shellRoot, content);
+    const reload = await reloadNginxIfRunning();
+    return {
+        prefixesAdded,
+        totalPrefixes: CORE_PHP_PREFIXES.length + prefixesAdded.length,
+        reload,
+    };
+}
+//# sourceMappingURL=addon-routes.js.map

package/dist/lib/ops/addon-routes.js.map

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