@stacksjs/features 0.74.4

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @stacksjs/features
+
+Which files and tables belong to which optional Stacks feature.
+
+Two very different callers need this manifest and neither should own it. The
+CLI installs and uninstalls a feature, so it needs the file list.
+The migration runner hides a disabled feature's migrations before a run, so it
+needs the table list.
+
+The manifest used to live in `@stacksjs/buddy`, and the migration runner
+reached into the CLI through a best-effort dynamic import to read it — so
+`@stacksjs/database` depended on `@stacksjs/buddy`, and the two sat inside a
+dependency cycle that no publish order could satisfy.
+
+```ts
+import { FEATURE_NAMES, migrationFeature, migrationTable } from '@stacksjs/features'
+
+migrationTable('0000000133-create-campaigns-table.sql') // 'campaigns'
+migrationFeature('0000000133-create-campaigns-table.sql') // 'marketing'
+```
+
+Nothing here reads config or touches a database — it is the manifest and three
+lookups over it. Deciding whether a feature is *enabled* is `@stacksjs/config`'s
+job, and acting on that is the caller's.

package/dist/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Parse a migration filename like `0000000045-create-posts-table.sql` or
+ * `0000000085-alter-posts-author_id.sql` to extract the table name it
+ * acts on. Returns `null` for filenames that don't match the
+ * recognised `create-<table>-table` / `alter-<table>-` shapes — those
+ * pass through the gate unchanged.
+ *
+ * Index migrations (`create-<table>_<col>_unique-index-in-<table>.sql`)
+ * use the trailing `-in-<table>.sql` segment as the source of truth
+ * since the leading segment includes the index name. The other
+ * forms read the table from the segment immediately after the verb.
+ */
+export declare function migrationTable(filename: string): string | null;
+/**
+ * Returns the feature that owns the given migration filename, or `null`
+ * if the migration isn't claimed by any feature (in which case it
+ * always runs). Used by the migration runner's gating pass.
+ */
+export declare function migrationFeature(filename: string): FeatureName | null;
+/**
+ * True when an application-owned, top-level model explicitly declares a table.
+ * This lets apps intentionally use generic names such as `payments` without
+ * their migrations being mistaken for disabled framework-feature scaffolding.
+ * Root models listed in FEATURE_FILES remain feature-owned and do not override
+ * the gate.
+ */
+export declare function appModelClaimsTable(table: string, root?: string): boolean;
+export declare const FEATURE_NAMES: readonly ['dashboard', 'commerce', 'cms', 'forms', 'marketing', 'monitoring', 'realtime', 'queue'];
+/**
+ * Per-feature stamped file/directory manifest. Paths are relative to the
+ * project root and mirror the layout that `./buddy new` lays down. Entries
+ * ending in `/` are directory trees (recursive remove on uninstall); bare
+ * paths are single files.
+ *
+ * A feature must also claim the shared files its own actions IMPORT.
+ * `app/Actions/Dashboard/dashboard-response.ts` is the case that bit: five
+ * features publish a subdirectory of `app/Actions/Dashboard/`, and the actions
+ * in each import `../dashboard-response`. Without it, `<feature>:install`
+ * copied 22 actions whose very first import did not resolve.
+ *
+ * Manifests intentionally overlap where features share scaffolding —
+ * `dashboard` claims the umbrella `app/Actions/Dashboard/` even though
+ * `app/Actions/Dashboard/Content/` is also claimed by `cms`. Both the
+ * uninstall delete and the doctor orphan check are idempotent
+ * (already-gone paths are skipped silently), so the overlap is safe.
+ *
+ * Adding a new file to one of these directories does **not** require a
+ * manifest update — directory entries are recursive. Only add an entry
+ * when a feature introduces a new top-level path the framework didn't
+ * already claim.
+ * @defaultValue
+ * ```ts
+ * {
+ *   forms: [ 'app/Models/Forms/', ],
+ *   cms: [ 'app/Actions/Cms/', 'app/Actions/Dashboard/Content/', 'app/Actions/Dashboard/dashboard-response.ts', 'app/Models/Content/', 'app/Models/Tag.ts', 'app/Models/Comment.ts', 'resources/views/dashboard/content/', ],
+ *   commerce: [ 'app/Actions/Commerce/', 'app/Actions/Dashboard/Commerce/', 'app/Actions/Dashboard/dashboard-response.ts', 'app/Models/commerce/', 'resources/components/Dashboard/Commerce/', 'resources/views/dashboard/commerce/', ],
+ *   dashboard: [ 'app/Actions/Dashboard/', 'resources/components/Dashboard/', 'resources/views/dashboard/', 'routes/dashboard.ts', 'routes/dashboard-api.ts', ],
+ *   marketing: [ 'app/Actions/Dashboard/Marketing/', 'app/Actions/Dashboard/dashboard-response.ts', 'app/Models/Campaign.ts', 'app/Models/CampaignSend.ts', 'app/Models/EmailList.ts', 'app/Models/EmailListSubscriber.ts', 'app/Models/SocialPost.ts', 'resources/components/Marketing/', 'resources/views/dashboard/marketing/', ],
+ *   monitoring: [ 'app/Actions/Monitoring/', 'app/Actions/TestErrorAction.ts', 'app/Models/Error.ts', 'functions/monitoring/', 'resources/views/dashboard/monitoring/', 'resources/views/dashboard/errors/', ],
+ *   realtime: [ 'app/Actions/Realtime/', 'app/Actions/Dashboard/Realtime/', 'app/Actions/Dashboard/dashboard-response.ts', 'app/Models/realtime/', 'app/Broadcasts/', 'functions/realtime/', 'resources/views/dashboard/realtime/', ],
+ *   queue: [ 'app/Actions/Queue/', 'app/Actions/Dashboard/Jobs/', 'app/Actions/Dashboard/dashboard-response.ts', 'app/Jobs/', 'app/Models/Job.ts', 'app/Models/FailedJob.ts', 'functions/jobs.ts', 'resources/views/dashboard/queue/', 'resources/views/dashboard/jobs/', ]
+ * }
+ * ```
+ */
+export declare const FEATURE_FILES: Record<FeatureName, readonly string[]>;
+/**
+ * Per-feature database table ownership (stacksjs/stacks#1854).
+ *
+ * Stacks generates SQL migrations from model files, so each feature's
+ * tables map 1:1 with the models in its `FEATURE_FILES.app/Models/...`
+ * entries. Listed here explicitly rather than derived at runtime so
+ * additions are visible in a single grep-able place and the migration
+ * gate doesn't depend on filesystem scanning at boot.
+ *
+ * The migration runner consults this when `config.<feature>.enabled =
+ * false`: matching `*-create-<table>-table.sql` (and `*-alter-<table>-*.sql`)
+ * files get hidden for the duration of the run, so a project that
+ * never installed CMS doesn't materialize `posts`, `pages`,
+ * `comments`, etc. on `./buddy migrate`.
+ *
+ * Tables on this list are scoped to a single feature. Tables shared
+ * across features (none today, but `categories` could end up here)
+ * should stay out of the manifest until that's resolved — the runner
+ * defaults to "run unless owned by a disabled feature".
+ * @defaultValue
+ * ```ts
+ * {
+ *   forms: ['forms', 'form_fields', 'form_submissions'],
+ *   cms: [ 'posts', 'pages', 'comments', 'tags', 'authors', 'categories', 'taggable_models', 'categorizable_models', 'commentables', 'page_revisions', 'redirects', 'menus', 'menu_items', ],
+ *   commerce: [ 'products', 'product_variants', 'product_units', 'manufacturers', 'orders', 'order_items', 'order_idempotency', 'carts', 'cart_items', 'payments', 'payment_methods', 'payment_products', 'payment_transactions', 'customers', 'subscribers', 'subscriber_emails', 'subscriptions', 'gift_cards', 'coupons', 'transactions', 'reviews', 'couriers', 'courier_pings', 'delivery_routes', 'delivery_stops', 'digital_deliveries', 'shipping_methods', 'shipping_rates', 'shipping_zones', 'license_keys', 'loyalty_points', 'loyalty_rewards', 'print_devices', 'receipts', 'tax_rates', 'waitlist_products', 'waitlist_restaurants', 'auctions', 'auction_items', 'bids', 'pledges', ],
+ *   dashboard: [ 'boards', 'board_columns', 'cards', 'card_labels', 'card_assignees', 'card_comments', 'labels', 'ci_run_states', 'ci_runner_samples', 'ci_runner_alert_states', 'requests', 'logs', ],
+ *   marketing: [ 'campaigns', 'campaign_sends', 'email_lists', 'email_list_subscribers', 'social_posts', 'mail_preferences', ],
+ *   monitoring: ['errors'],
+ *   realtime: ['websockets'],
+ *   queue: ['jobs', 'failed_jobs']
+ * }
+ * ```
+ */
+export declare const FEATURE_TABLES: Record<FeatureName, readonly string[]>;
+export type FeatureName = (typeof FEATURE_NAMES)[number];

package/dist/index.js

@@ -0,0 +1,2 @@
+// @bun
+import{existsSync as p,readdirSync as d,readFileSync as m}from"fs";import{join as t}from"path";import{projectPath as l}from"@stacksjs/path";var i=["dashboard","commerce","cms","forms","marketing","monitoring","realtime","queue"],u={forms:["app/Models/Forms/"],cms:["app/Actions/Cms/","app/Actions/Dashboard/Content/","app/Actions/Dashboard/dashboard-response.ts","app/Models/Content/","app/Models/Tag.ts","app/Models/Comment.ts","resources/views/dashboard/content/"],commerce:["app/Actions/Commerce/","app/Actions/Dashboard/Commerce/","app/Actions/Dashboard/dashboard-response.ts","app/Models/commerce/","resources/components/Dashboard/Commerce/","resources/views/dashboard/commerce/"],dashboard:["app/Actions/Dashboard/","resources/components/Dashboard/","resources/views/dashboard/","routes/dashboard.ts","routes/dashboard-api.ts"],marketing:["app/Actions/Dashboard/Marketing/","app/Actions/Dashboard/dashboard-response.ts","app/Models/Campaign.ts","app/Models/CampaignSend.ts","app/Models/EmailList.ts","app/Models/EmailListSubscriber.ts","app/Models/SocialPost.ts","resources/components/Marketing/","resources/views/dashboard/marketing/"],monitoring:["app/Actions/Monitoring/","app/Actions/TestErrorAction.ts","app/Models/Error.ts","functions/monitoring/","resources/views/dashboard/monitoring/","resources/views/dashboard/errors/"],realtime:["app/Actions/Realtime/","app/Actions/Dashboard/Realtime/","app/Actions/Dashboard/dashboard-response.ts","app/Models/realtime/","app/Broadcasts/","functions/realtime/","resources/views/dashboard/realtime/"],queue:["app/Actions/Queue/","app/Actions/Dashboard/Jobs/","app/Actions/Dashboard/dashboard-response.ts","app/Jobs/","app/Models/Job.ts","app/Models/FailedJob.ts","functions/jobs.ts","resources/views/dashboard/queue/","resources/views/dashboard/jobs/"]},b={forms:["forms","form_fields","form_submissions"],cms:["posts","pages","comments","tags","authors","categories","taggable_models","categorizable_models","commentables","page_revisions","redirects","menus","menu_items"],commerce:["products","product_variants","product_units","manufacturers","orders","order_items","order_idempotency","carts","cart_items","payments","payment_methods","payment_products","payment_transactions","customers","subscribers","subscriber_emails","subscriptions","gift_cards","coupons","transactions","reviews","couriers","courier_pings","delivery_routes","delivery_stops","digital_deliveries","shipping_methods","shipping_rates","shipping_zones","license_keys","loyalty_points","loyalty_rewards","print_devices","receipts","tax_rates","waitlist_products","waitlist_restaurants","auctions","auction_items","bids","pledges"],dashboard:["boards","board_columns","cards","card_labels","card_assignees","card_comments","labels","ci_run_states","ci_runner_samples","ci_runner_alert_states","requests","logs"],marketing:["campaigns","campaign_sends","email_lists","email_list_subscribers","social_posts","mail_preferences"],monitoring:["errors"],realtime:["websockets"],queue:["jobs","failed_jobs"]};function _(r){let o=r.match(/-in-([a-z0-9_]+)\.sql$/i);if(o)return o[1]??null;let s=r.match(/-create-([a-z0-9_]+)-table\.sql$/i);if(s)return s[1]??null;let a=r.match(/-alter-([a-z0-9_]+)-/i);if(a)return a[1]??null;return null}function M(r){let o=_(r);if(!o)return null;for(let s of i)if(b[s].includes(o))return s;return null}function A(r,o=l()){let s=t(o,"app/Models");if(!p(s))return!1;let a=new Set(i.flatMap((e)=>u[e]).filter((e)=>e.startsWith("app/Models/")&&!e.endsWith("/"))),n=r.replace(/[.*+?^${}()|[\]\\]/g,"\\$&"),c=new RegExp(`\\btable\\s*:\\s*['"]${n}['"]`);for(let e of d(s,{withFileTypes:!0})){if(!e.isFile()||!/\.[cm]?[jt]s$/.test(e.name))continue;if(a.has(`app/Models/${e.name}`))continue;if(c.test(m(t(s,e.name),"utf8")))return!0}return!1}export{u as FEATURE_FILES,i as FEATURE_NAMES,b as FEATURE_TABLES,A as appModelClaimsTable,M as migrationFeature,_ as migrationTable};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@stacksjs/features",
+  "type": "module",
+  "version": "0.74.4",
+  "description": "Which files and tables belong to which optional Stacks feature.",
+  "author": "Chris Breuer",
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/chrisbbreuer",
+  "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/features#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stacks.git",
+    "directory": "./storage/framework/core/features"
+  },
+  "bugs": {
+    "url": "https://github.com/stacksjs/stacks/issues"
+  },
+  "keywords": [
+    "features",
+    "migrations",
+    "manifest",
+    "stacks"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./dist/index.js",
+      "import": "./dist/index.js"
+    },
+    "./*": {
+      "import": "./dist/*"
+    }
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build.ts",
+    "typecheck": "bun --bun tsc --noEmit"
+  },
+  "dependencies": {
+    "@stacksjs/path": "0.74.4"
+  }
+}