@objectstack/service-package 1.0.0 → 4.0.4

package/README.md

@@ -0,0 +1,125 @@
+# @objectstack/service-package
+
+> Runtime package publishing, retrieval, and lifecycle management for ObjectStack — the storage layer behind the dynamic marketplace.
+
+[![npm](https://img.shields.io/npm/v/@objectstack/service-package.svg)](https://www.npmjs.com/package/@objectstack/service-package)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+## Overview
+
+`service-package` persists ObjectStack packages — the unit of metadata distribution consisting of a `manifest` plus its `objects`, `views`, `apps`, `flows`, `agents`, `tools`, and `translations` — into the `sys_packages` system table so they can be published, listed, and delivered to runtime kernels that load them through `@objectstack/service-marketplace`.
+
+Typical consumers:
+
+- **Marketplace servers** that host first-party and third-party packages.
+- **Self-hosted platforms** that want an internal registry for tenants' custom metadata.
+- **CI pipelines** that publish package artifacts from a Git repository.
+
+## Installation
+
+```bash
+pnpm add @objectstack/service-package
+```
+
+## Quick Start
+
+```typescript
+import { ObjectKernel } from '@objectstack/core';
+import { PackageServicePlugin, type PackageService } from '@objectstack/service-package';
+
+const kernel = new ObjectKernel();
+
+// Register after a driver/ObjectQL plugin so `ctx.getService('objectql')` resolves.
+kernel.use(new PackageServicePlugin());
+
+await kernel.bootstrap();
+
+const packages = kernel.getService<PackageService>('package')!;
+
+await packages.publish({
+  manifest: {
+    id: 'crm',
+    version: '1.2.0',
+    name: 'CRM Package',
+    /* …full ObjectStackManifest… */
+  },
+  metadata: {
+    objects: [/* … */],
+    views:   [/* … */],
+    apps:    [/* … */],
+  },
+});
+
+const latest = await packages.get('crm'); // defaults to 'latest'
+const all    = await packages.list();
+await packages.delete('crm', '1.0.0');
+```
+
+## Key Exports
+
+| Export | Kind | Description |
+|:---|:---|:---|
+| `PackageServicePlugin` | class (default) | Kernel plugin that installs the service and ensures the `sys_packages` table exists. |
+| `PackageService` | interface | Service contract registered under `'package'`: `publish`, `get`, `list`, `delete`. |
+| `PackageRecord` | type | Stored row shape: `id`, `version`, `manifest`, `metadata`, `hash`, `created_at`, `updated_at`. |
+| `PackageMetadata` | type | Artifact container for `objects`, `views`, `apps`, `flows`, `agents`, `tools`, `translations`. |
+
+## Behavior
+
+- **Upsert by (id, version)** — re-publishing the same version overwrites `manifest`, `metadata`, `hash`, and `updated_at`.
+- **Integrity hash** — SHA-256 of `{ manifest, metadata }` is computed on publish and stored alongside the row.
+- **`get(id, 'latest')`** resolves to the most recently inserted version. Use an explicit version string for pinned lookups.
+- **`list()`** returns the latest version per package, ordered by `created_at DESC`.
+- **System bypass** — the service uses `IDataEngine.execute()` directly (raw SQL), so security/RLS middleware is not applied to registry storage; callers are responsible for authorizing publish/delete at their API layer.
+
+## Storage Schema
+
+`service-package` creates (idempotently) the following table on `start()`:
+
+```sql
+CREATE TABLE IF NOT EXISTS sys_packages (
+  id         TEXT NOT NULL,
+  version    TEXT NOT NULL,
+  manifest   TEXT NOT NULL,
+  metadata   TEXT NOT NULL,
+  hash       TEXT NOT NULL,
+  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (id, version)
+);
+
+CREATE INDEX IF NOT EXISTS idx_packages_latest
+  ON sys_packages(id, created_at DESC);
+```
+
+## Requirements
+
+- A driver plugin that registers an `IDataEngine` under the service name `'objectql'` with `execute()` support — typically [`@objectstack/driver-sql`](../../plugins/driver-sql) or [`@objectstack/driver-turso`](../../plugins/driver-turso). `@objectstack/driver-memory` can be used for tests but does not persist across restarts.
+
+## When to use
+
+- ✅ Building a marketplace backend or internal package registry.
+- ✅ Distributing metadata-only packages to many runtime instances.
+- ✅ Versioned audit trail of schema/UI/flow changes.
+
+## When not to use
+
+- ❌ Not a package manager for npm/TypeScript source packages — use npm.
+- ❌ Not a runtime plugin loader — pair with [`@objectstack/service-marketplace`](../service-marketplace) or a custom loader for that.
+
+## Related Packages
+
+- [`@objectstack/core`](../../core) — kernel hosting this plugin.
+- [`@objectstack/spec`](../../spec) — provides `ObjectStackManifest` and `IDataEngine` contracts.
+- [`@objectstack/driver-sql`](../../plugins/driver-sql), [`@objectstack/driver-turso`](../../plugins/driver-turso) — supply the `'objectql'` service.
+
+## Links
+
+- 📖 Docs: <https://objectstack.ai/docs>
+- 📚 API Reference: <https://objectstack.ai/docs/references>
+- 🧭 Protocol: <https://objectstack.ai/docs/protocol>
+- 🧪 Examples: [`examples/`](../../../examples)
+
+## License
+
+Apache-2.0 © ObjectStack

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/service-package",
-  "version": "1.0.0",
+  "version": "4.0.4",
   "license": "Apache-2.0",
   "description": "Package management service for ObjectStack — publish, install, and manage packages",
   "type": "module",
@@ -22,6 +22,31 @@
     "typescript": "^6.0.2",
     "vitest": "^4.1.4"
   },
+  "keywords": [
+    "objectstack",
+    "service",
+    "package",
+    "registry",
+    "marketplace"
+  ],
+  "author": "ObjectStack",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/objectstack-ai/framework.git",
+    "directory": "packages/services/service-package"
+  },
+  "homepage": "https://objectstack.ai/docs",
+  "bugs": "https://github.com/objectstack-ai/framework/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",
     "test": "vitest run --passWithNoTests"

package/.turbo/turbo-build.log

@@ -1,22 +0,0 @@
-
-> @objectstack/service-package@1.0.0 build /home/runner/work/framework/framework/packages/services/service-package
-> tsup --config ../../../tsup.config.ts
-
-CLI Building entry: src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /home/runner/work/framework/framework/tsup.config.ts
-CLI Target: es2020
-CLI Cleaning output folder
-ESM Build start
-CJS Build start
-ESM dist/index.js     5.10 KB
-ESM dist/index.js.map 9.90 KB
-ESM ⚡️ Build success in 64ms
-CJS dist/index.cjs     6.14 KB
-CJS dist/index.cjs.map 9.95 KB
-CJS ⚡️ Build success in 68ms
-DTS Build start
-DTS ⚡️ Build success in 14387ms
-DTS dist/index.d.ts  1.38 KB
-DTS dist/index.d.cts 1.38 KB

package/src/index.ts

@@ -1,216 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { Plugin, PluginContext } from '@objectstack/core';
-import { createHash } from 'node:crypto';
-import type { ObjectStackManifest } from '@objectstack/spec/kernel';
-import type { IDataEngine } from '@objectstack/spec/contracts';
-
-export interface PackageMetadata {
-  objects?: any[];
-  views?: any[];
-  apps?: any[];
-  flows?: any[];
-  agents?: any[];
-  tools?: any[];
-  translations?: any[];
-}
-
-export interface PackageRecord {
-  id: string;
-  version: string;
-  manifest: ObjectStackManifest;
-  metadata: PackageMetadata;
-  hash: string;
-  created_at: string;
-  updated_at: string;
-}
-
-export interface PackageService {
-  publish(data: { manifest: ObjectStackManifest; metadata: PackageMetadata }): Promise<{ success: boolean; error?: string }>;
-  get(packageId: string, version?: string): Promise<PackageRecord | null>;
-  list(): Promise<PackageRecord[]>;
-  delete(packageId: string, version?: string): Promise<{ success: boolean }>;
-}
-
-/**
- * Package Management Service Plugin
- *
- * Provides package publishing, retrieval, and management capabilities.
- * Stores package metadata in the sys.packages table for dynamic loading.
- */
-export class PackageServicePlugin implements Plugin {
-  name = 'package-service';
-
-  async init(ctx: PluginContext): Promise<void> {
-    // Service will be registered in start() after ObjectQL is available
-    ctx.logger.debug('Package service plugin initialized');
-  }
-
-  async start(ctx: PluginContext): Promise<void> {
-    const logger = ctx.logger;
-
-    // Get ObjectQL service (available in start() hook after dependencies are initialized)
-    const objectql = ctx.getService<IDataEngine>('objectql');
-    if (!objectql || !objectql.execute) {
-      throw new Error('ObjectQL service with execute() support is required for PackageService');
-    }
-
-    // Create sys_packages table if it doesn't exist
-    try {
-      await this.ensureTable(objectql, logger);
-    } catch (error) {
-      logger.error('Failed to create sys_packages table', error as Error);
-      throw error;
-    }
-
-    // Create the package service
-    const packageService: PackageService = {
-      async publish(data: { manifest: ObjectStackManifest; metadata: PackageMetadata }) {
-        try {
-          const hash = createHash('sha256')
-            .update(JSON.stringify({ manifest: data.manifest, metadata: data.metadata }))
-            .digest('hex');
-
-          await objectql.execute!({
-            sql: `
-              INSERT INTO sys_packages (id, version, manifest, metadata, hash, created_at, updated_at)
-              VALUES (?, ?, ?, ?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
-              ON CONFLICT(id, version) DO UPDATE SET
-                manifest = excluded.manifest,
-                metadata = excluded.metadata,
-                hash = excluded.hash,
-                updated_at = CURRENT_TIMESTAMP
-            `,
-            args: [
-              data.manifest.id,
-              data.manifest.version,
-              JSON.stringify(data.manifest),
-              JSON.stringify(data.metadata),
-              hash,
-            ],
-          });
-
-          logger.info(`Published package: ${data.manifest.id}@${data.manifest.version}`);
-          return { success: true };
-        } catch (error) {
-          logger.error('Failed to publish package', error as Error);
-          return {
-            success: false,
-            error: (error as Error).message,
-          };
-        }
-      },
-
-      async get(packageId: string, version: string = 'latest') {
-        try {
-          const sql = version === 'latest'
-            ? `SELECT * FROM sys_packages WHERE id = ? ORDER BY created_at DESC LIMIT 1`
-            : `SELECT * FROM sys_packages WHERE id = ? AND version = ?`;
-
-          const args = version === 'latest' ? [packageId] : [packageId, version];
-          const result = await objectql.execute!({ sql, args });
-
-          if (result.rows.length === 0) {
-            return null;
-          }
-
-          const row = result.rows[0];
-          return {
-            id: row.id,
-            version: row.version,
-            manifest: JSON.parse(row.manifest),
-            metadata: JSON.parse(row.metadata),
-            hash: row.hash,
-            created_at: row.created_at,
-            updated_at: row.updated_at,
-          };
-        } catch (error) {
-          logger.error(`Failed to get package: ${packageId}`, error as Error);
-          return null;
-        }
-      },
-
-      async list() {
-        try {
-          const result = await objectql.execute!({
-            sql: `
-              SELECT * FROM sys_packages
-              WHERE (id, created_at) IN (
-                SELECT id, MAX(created_at) FROM sys_packages GROUP BY id
-              )
-              ORDER BY created_at DESC
-            `,
-          });
-
-          return result.rows.map((row: any) => ({
-            id: row.id,
-            version: row.version,
-            manifest: JSON.parse(row.manifest),
-            metadata: JSON.parse(row.metadata),
-            hash: row.hash,
-            created_at: row.created_at,
-            updated_at: row.updated_at,
-          }));
-        } catch (error) {
-          logger.error('Failed to list packages', error as Error);
-          return [];
-        }
-      },
-
-      async delete(packageId: string, version?: string) {
-        try {
-          const sql = version
-            ? `DELETE FROM sys_packages WHERE id = ? AND version = ?`
-            : `DELETE FROM sys_packages WHERE id = ?`;
-
-          const args = version ? [packageId, version] : [packageId];
-          await objectql.execute!({ sql, args });
-
-          logger.info(`Deleted package: ${packageId}${version ? `@${version}` : ''}`);
-          return { success: true };
-        } catch (error) {
-          logger.error('Failed to delete package', error as Error);
-          return { success: false };
-        }
-      },
-    };
-
-    ctx.registerService('package', packageService);
-    logger.info('Package service initialized');
-  }
-
-  private async ensureTable(objectql: IDataEngine, logger: any): Promise<void> {
-    try {
-      // Create the sys_packages table
-      await objectql.execute!({
-        sql: `
-          CREATE TABLE IF NOT EXISTS sys_packages (
-            id TEXT NOT NULL,
-            version TEXT NOT NULL,
-            manifest TEXT NOT NULL,
-            metadata TEXT NOT NULL,
-            hash TEXT NOT NULL,
-            created_at TEXT DEFAULT CURRENT_TIMESTAMP,
-            updated_at TEXT DEFAULT CURRENT_TIMESTAMP,
-            PRIMARY KEY (id, version)
-          )
-        `,
-      });
-
-      // Create index for faster latest version queries
-      await objectql.execute!({
-        sql: `
-          CREATE INDEX IF NOT EXISTS idx_packages_latest
-          ON sys_packages(id, created_at DESC)
-        `,
-      });
-
-      logger.debug('sys_packages table ensured');
-    } catch (error) {
-      // Table might already exist, log and continue
-      logger.debug('sys_packages table creation skipped (may already exist)');
-    }
-  }
-}
-
-export { PackageServicePlugin as default };

package/tsconfig.json

@@ -1,17 +0,0 @@
-{
-  "extends": "../../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "src",
-    "types": [
-      "node"
-    ]
-  },
-  "include": [
-    "src"
-  ],
-  "exclude": [
-    "node_modules",
-    "dist"
-  ]
-}