@promptframe/cli 0.1.64 → 0.1.67

package/README.md

@@ -1,10 +1,14 @@
 # @promptframe/cli
 
+`package` 和目录形式的 `upload` 使用所选组件目录及其子目录中的 `.gitignore`，支持嵌套覆盖、`!` 和目录规则；不读取组件目录外的 Git 配置。`node_modules`、`dist`、`.git`、`.promptframe`、`.component-packages` 仍固定排除。将本地出图和测试产物放在明确忽略的目录中。
+
+必需文件、manifest 声明的源码/props schema 和 `public/` 资源不能被静默排除；规则命中时返回 `package.required_file.ignored`，应修正规则后再打包。保留文件仍接受原安全扫描，原始 lockfile 不入包，脱敏 lockfile evidence 保留。
+
 PromptFrame component authoring CLI.
 
 Use it to inspect the public component standard, check component folders, validate manifests, inspect the local preview envelope, package source archives, upload components, check build status, rebuild evidence indexes, and rerun layout/security probes.
 
-Current source baseline is `@promptframe/cli@0.1.64`, `@promptframe/contracts@0.1.32`, `@promptframe/component-kit@0.1.26`, and `create-promptframe-component@0.1.54`. The published CLI consumes the contracts AST-aware public security policy evaluator, reports `securityPolicyDigest` / `securityEvaluatorMode` in JSON output, rejects red-team browser capability vectors such as Image/Audio beacons, Worker/SharedWorker, `window.open`, `postMessage`, dynamic script/iframe creation, browser fingerprinting, storage/cookie access, and dangerous HTML, reports `publicResources` for component-level public assets, keeps native `<img>` / `<video>` source checks case-sensitive so Remotion `<Img>` / `<Video>` remain valid, validates preview props against statically declared `propsSchema` fields and requires readable public prop descriptions, enforces strict Slot-first layout/source diagnostics, supports endpoint discovery, project list/current diagnostics, self-service CI token create/list/revoke, single-component and workspace GitHub workflow setup with `promptframe-workflow-version: 2`, `setup-ci --upgrade` stale-template repair, dynamic workspace matrix discovery, `RUNNER_LABELS` and pnpm 10 workflow support, pnpm workspace root lockfile evidence without component symlinks, `promptframe-workspace.json` validation, workspace root `check .` / `upload .` auto-detection, explicit `workspace:*` shared-package diagnostics, workspace upload source metadata headers, packages sanitized lockfile evidence for platform admission, release notes forwarding to upload, stderr NDJSON upload progress for `--json`, human-readable token kind/expiry summaries for `login`, `whoami`, and authenticated `upload`, server version auto-bump notes, and supports `status --fail-on-build-failed` for CI build-status gating.
+Current source baseline is `@promptframe/cli@0.1.67`, `@promptframe/contracts@0.1.35`, `@promptframe/component-kit@0.1.29`, and `create-promptframe-component@0.1.57`. The published CLI consumes the contracts AST-aware public security policy evaluator, reports `securityPolicyDigest` / `securityEvaluatorMode` in JSON output, rejects red-team browser capability vectors such as Image/Audio beacons, Worker/SharedWorker, `window.open`, `postMessage`, dynamic script/iframe creation, browser fingerprinting, storage/cookie access, and dangerous HTML, reports `publicResources` for component-level public assets, keeps native `<img>` / `<video>` source checks case-sensitive so Remotion `<Img>` / `<Video>` remain valid, validates preview props against statically declared `propsSchema` fields and requires readable public prop descriptions, enforces strict Slot-first layout/source diagnostics, supports endpoint discovery, project list/current diagnostics, self-service CI token create/list/revoke, single-component and workspace GitHub workflow setup with `promptframe-workflow-version: 2`, `setup-ci --upgrade` stale-template repair, dynamic workspace matrix discovery, `RUNNER_LABELS` and pnpm 10 workflow support, pnpm workspace root lockfile evidence without component symlinks, `promptframe-workspace.json` validation, workspace root `check .` / `upload .` auto-detection, explicit `workspace:*` shared-package diagnostics, workspace upload source metadata headers, packages sanitized lockfile evidence for platform admission, release notes forwarding to upload, stderr NDJSON upload progress for `--json`, human-readable token kind/expiry summaries for `login`, `whoami`, and authenticated `upload`, server version auto-bump notes, and supports `status --fail-on-build-failed` for CI build-status gating.
 
 ```bash
 npm install -D @promptframe/cli
@@ -202,3 +206,34 @@ promptframe dev stop .
 关闭开发面板不停止连接；切换账号或作品、关闭页面会断开。刷新页面后重新粘贴连接JSON。停止或替换仅操作本工作区的实际实例；无法确认实例退出时命令报错，不自动强制终止进程。
 
 上传组件后，用准确的正式 `componentRef` 替换作品节点引用并移除该节点的 `componentSource`。仅上传成功不会自动改变作品的选源。确认作品已使用正式引用且不再需要本地预览后，可执行 `promptframe dev stop .`。
+
+## 素材引用槽与本地私有预览
+
+在 schema 中用 `promptFrameResourceSchema` 声明素材参数，在组件中用 `promptFrameResource` 消费。参数保存 public 路径或 `asset-proxy://` 引用；组件不读取凭据，也不调用平台解析接口。
+
+```ts
+import { z } from 'zod';
+import { promptFrameResourceSchema } from '@promptframe/contracts';
+export const propsSchema = z.object({
+  illustration: promptFrameResourceSchema({
+    kinds: ['image'], sources: ['public', 'asset'],
+    accept: ['image/png', 'image/jpeg'], maxFileBytes: 16 * 1024 * 1024,
+  }).describe('展示图片').default('/example.png'),
+});
+```
+
+组件使用 `<Img src={promptFrameResource(props, props.illustration)} />`。本地、Studio 预览和正式渲染使用同一写法；解析由宿主完成。正式渲染缺失、错误类型或越权引用会报错，不自动替换作品内容。
+
+新模板已启用 Vite 适配器。自定义旧项目在 `vite.config.ts` 的 plugins 中加入 `promptFramePreviewResources()`（从 `@promptframe/cli/preview` 导入），再运行 `promptframe sync . --apply` 更新预览壳；已有 React 插件等设置继续保留。适配器仅在本机 loopback 开发服务中运行，不导入组件业务代码。
+
+```bash
+promptframe resource set . --prop /illustration --file ./my-selected.png
+promptframe resource status .
+promptframe resource clear .
+```
+
+本人明确选择的 PNG、JPEG、WebP 文件最大 16MiB，并受槽声明的 MIME/大小限制。CLI 记录原文件身份和 SHA，不复制原件；每次读取重新核对。选择存入 ignored 的 `.promptframe/local-previews/resources.json`，不会改公开 `preview-props.json`，打包固定排除此目录。选择最多 16 项，24 小时后不再提供读取；`resource clear` 只移除受管选择记录，不删除原始文件。没有后台清理进程。
+
+平台素材使用同一选择命令的 `--asset-ref` 和原作品 `--session-id`，不得与 `--file` 同用。项目来自正常 `promptframe init` 写入的无凭据上下文。需要先沿正常 `promptframe login --endpoint <平台API> --with-assets` 授予 `asset.read`；旧组件上传凭据不会自动扩大权限。开发服务复用现有 CLI 凭据，逐次请求当前用户、项目与作品范围内的短时只读表示，核字节 SHA 后向浏览器提供本机地址。凭据、签名 URL 和私有文件路径不会发送给组件。断网、撤权、文件变化或选择过期时，预览明确提示不可用并标明正在展示包内示例；恢复条件后刷新。
+
+市场预览的素材选择读取访问者当前作品中的就绪素材，不改变组件包或上传新素材。正式使用时将合法素材引用冻结在 Spec，渲染入口沿原授权、素材存储和预下载合同准备本地表示；签名 URL 不保存到 Spec。

package/dist/configuration.d.ts

@@ -0,0 +1,13 @@
+export declare class CliCredentialError extends Error {
+    readonly code: 'cli.auth.token_expired';
+    constructor(code: 'cli.auth.token_expired');
+}
+export declare function readCliConfiguration(path: string): Record<string, unknown>;
+/** Shared read-only access to the existing credential; never logs or writes it. */
+export declare function cliBearerToken(input: {
+    endpoint: string;
+    explicit?: string;
+    configuration: Record<string, unknown>;
+    now?: () => number;
+}): string | undefined;
+//# sourceMappingURL=configuration.d.ts.map

package/dist/configuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../src/configuration.ts"],"names":[],"mappings":"AAEA,qBAAa,kBAAmB,SAAQ,KAAK;IAC/B,QAAQ,CAAC,IAAI,EAAE,wBAAwB;gBAA9B,IAAI,EAAE,wBAAwB;CACpD;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAM1E;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACjG,GAAG,MAAM,GAAG,SAAS,CAWrB"}

package/dist/configuration.js

@@ -0,0 +1,36 @@
+import { existsSync, readFileSync } from 'node:fs';
+export class CliCredentialError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+export function readCliConfiguration(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const value = JSON.parse(readFileSync(path, 'utf8'));
+        return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Shared read-only access to the existing credential; never logs or writes it. */
+export function cliBearerToken(input) {
+    if (input.explicit)
+        return input.explicit;
+    const credential = input.configuration.credential;
+    if (!credential || typeof credential !== 'object' || Array.isArray(credential))
+        return undefined;
+    const row = credential;
+    const normalize = (value) => value.replace(/\/+$/, '');
+    if (typeof row.endpoint !== 'string' || normalize(row.endpoint) !== normalize(input.endpoint))
+        return undefined;
+    if (typeof row.expiresAt === 'string' && Date.parse(row.expiresAt) <= (input.now ?? Date.now)()) {
+        throw new CliCredentialError('cli.auth.token_expired');
+    }
+    return typeof row.tokenSecret === 'string' ? row.tokenSecret : undefined;
+}
+//# sourceMappingURL=configuration.js.map

package/dist/configuration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.js","sourceRoot":"","sources":["../src/configuration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEnD,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACtB;IAArB,YAAqB,IAA8B;QAAI,KAAK,CAAC,IAAI,CAAC,CAAC;QAA9C,SAAI,GAAJ,IAAI,CAA0B;IAAiB,CAAC;CACtE;AAED,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;QAC9D,OAAO,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAgC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7G,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,EAAE,CAAC;IAAC,CAAC;AACxB,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,cAAc,CAAC,KAE9B;IACC,IAAI,KAAK,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC,QAAQ,CAAC;IAC1C,MAAM,UAAU,GAAG,KAAK,CAAC,aAAa,CAAC,UAAU,CAAC;IAClD,IAAI,CAAC,UAAU,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QAAE,OAAO,SAAS,CAAC;IACjG,MAAM,GAAG,GAAG,UAAqC,CAAC;IAClD,MAAM,SAAS,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC/D,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAC;IAChH,IAAI,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QAChG,MAAM,IAAI,kBAAkB,CAAC,wBAAwB,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,OAAO,GAAG,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3E,CAAC"}

package/dist/index.js

@@ -6,12 +6,15 @@ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync,
 import os from 'node:os';
 import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 import { inflateRawSync } from 'node:zlib';
-import { COMPONENT_MANIFEST_SCHEMA_VERSION, COMPONENT_PUBLIC_RESOURCES_CONTRACT_VERSION, COMPONENT_REF_VERSION, COMPONENT_STANDARD_SOURCE_HASH, COMPONENT_STANDARD_VERSION, PROMPTFRAME_AUTHORING_STANDARD_RELEASE, PROMPTFRAME_PUBLIC_RESOURCE_LIMITS, PROMPTFRAME_PUBLIC_RESOURCE_POLICY, PROMPTFRAME_PUBLIC_SECURITY_POLICY, PROMPTFRAME_PUBLIC_SECURITY_POLICY_DIGEST, PROMPTFRAME_PUBLIC_STANDARD_POLICY, PROMPTFRAME_LAYOUT_POLICY_RULE_IDS, PROMPTFRAME_CONTRACTS_VERSION, PROMPTFRAME_PUBLIC_DEPENDENCY_POLICY, detectPromptFrameUnknownCustomStyleProps, evaluatePromptFrameLayoutPolicy, evaluatePromptFrameDependencyPolicy, authoringUploadTargetSchema, parseComponentManifest, } from '@promptframe/contracts';
+import { cliBearerToken, readCliConfiguration } from './configuration.js';
+import ignore from 'ignore';
+import { COMPONENT_MANIFEST_SCHEMA_VERSION, COMPONENT_PUBLIC_RESOURCES_CONTRACT_VERSION, COMPONENT_REF_VERSION, COMPONENT_STANDARD_SOURCE_HASH, COMPONENT_STANDARD_VERSION, PROMPTFRAME_AUTHORING_STANDARD_RELEASE, PROMPTFRAME_PUBLIC_RESOURCE_LIMITS, PROMPTFRAME_PUBLIC_RESOURCE_POLICY, PROMPTFRAME_PUBLIC_SECURITY_POLICY, PROMPTFRAME_PUBLIC_SECURITY_POLICY_DIGEST, PROMPTFRAME_PUBLIC_STANDARD_POLICY, PROMPTFRAME_LAYOUT_POLICY_RULE_IDS, PROMPTFRAME_CONTRACTS_VERSION, PROMPTFRAME_PUBLIC_DEPENDENCY_POLICY, detectPromptFrameUnknownCustomStyleProps, evaluatePromptFrameLayoutPolicy, evaluatePromptFrameDependencyPolicy, collectPromptFrameResourceReferences, authoringUploadTargetSchema, parseComponentManifest, } from '@promptframe/contracts';
 import { evaluatePromptFrameSecurityPolicySource, } from '@promptframe/contracts/security-evaluator';
 import { evaluatePromptFrameSchemaSource, } from '@promptframe/contracts/schema-evaluator';
 import { applyPackageChanges, buildFreshnessDecision, computePackageChanges, computePackageFreshnessDiagnostics, computeScaffoldFreshnessDiagnostics, resolveLocalPreviewScript, } from './lifecycle.js';
 import { evaluateLocalReusability, reusabilityDiagnostics, } from './reusability.js';
 import { assertPreviewEnvelope, writeLocalPreviewReport, } from './preview-report.js';
+import { capturePreviewResourceFile, clearPreviewResourceDraft, previewResourcePropPath, readPreviewResourceDraft, writePreviewResourceSelection } from './preview-resource-draft.js';
 const command = process.argv[2] ?? 'help';
 const args = process.argv.slice(3);
 const REQUIRED_COMPONENT_FILES = PROMPTFRAME_PUBLIC_STANDARD_POLICY.requiredFiles;
@@ -96,6 +99,9 @@ async function run(name, argv) {
         case 'preview':
             preview(argv);
             break;
+        case 'resource':
+            resourceCommand(argv);
+            break;
         case 'dev':
             await dev(argv);
             break;
@@ -383,7 +389,7 @@ function sync(argv) {
     const nextFiles = [
         {
             path: GENERATED_PREVIEW_ROOT_PATH,
-            contents: renderPromptFrameThinPreviewRoot(),
+            contents: renderPromptFrameThinPreviewRoot(hasResourcePreviewAdapter(dir)),
         },
         {
             path: DEV_PUBLIC_RESOURCES_MODULE_PATH,
@@ -541,6 +547,59 @@ async function dev(argv) {
         return;
     await runDevServer(dir, devCommand);
 }
+function resourceCommand(argv) {
+    const [action, directory] = positionalArgs(argv), root = resolve(directory ?? '.');
+    if (action === 'clear') {
+        clearPreviewResourceDraft(root);
+        printJson({ command: 'resource.clear', status: 'cleared', originalFilesDeleted: 0 });
+        return;
+    }
+    if (action === 'status') {
+        const draft = readPreviewResourceDraft(root);
+        printJson({ command: 'resource.status', selectedCount: draft?.selections.length ?? 0,
+            updatedAt: draft?.updatedAt, credentialsIncluded: false });
+        return;
+    }
+    if (action !== 'set')
+        fail('Use resource set|status|clear <component-directory>.', 'preview.resource.command_invalid', 2);
+    const prop = valueAfter(argv, '--prop'), file = valueAfter(argv, '--file'), reference = valueAfter(argv, '--asset-ref');
+    if (!prop || !!file === !!reference)
+        fail('Select --prop /field with exactly one --file or --asset-ref.', 'preview.resource.selection_invalid', 2);
+    const manifest = validateComponentDirectory(root), envelope = readPreviewProps(root);
+    const facts = evaluatePromptFrameSchemaSource(readFileSync(join(root, manifest.entry.propsSchemaPath), 'utf8'));
+    const props = structuredClone(envelope.props ?? {}), keys = previewResourcePropPath(prop);
+    let object = props;
+    for (const key of keys.slice(0, -1)) {
+        if (!object || typeof object !== 'object' || !Object.hasOwn(object, key))
+            fail('Resource field is missing.', 'preview.resource.prop_missing');
+        object = object[key];
+    }
+    if (!object || typeof object !== 'object')
+        fail('Resource field is missing.', 'preview.resource.prop_missing');
+    object[keys.at(-1)] = reference ?? '/local-preview.png';
+    const slot = collectPromptFrameResourceReferences({ type: 'object', properties: facts.properties }, props)
+        .find(row => JSON.stringify(row.path) === JSON.stringify(keys));
+    if (facts.status !== 'resolved' || !slot)
+        fail('Use promptFrameResourceSchema for this field.', 'preview.resource.slot_missing');
+    const selectedFile = file ? capturePreviewResourceFile(file) : undefined;
+    if (selectedFile && (!slot.slot.sources.includes('public') || !slot.slot.kinds.includes('image')
+        || slot.slot.maxFileBytes !== undefined && selectedFile.size > slot.slot.maxFileBytes
+        || slot.slot.accept?.length && !slot.slot.accept.some(type => type === '*/*' || type === selectedFile.contentType
+            || type.endsWith('/*') && selectedFile.contentType.startsWith(type.slice(0, -1)))))
+        fail('Selected file does not match the declared slot.', 'preview.resource.file_rejected');
+    const sessionId = valueAfter(argv, '--session-id');
+    if (reference && !sessionId)
+        fail('A platform asset needs its original --session-id.', 'preview.resource.scope_required', 2);
+    const ignored = join(root, '.gitignore'), oldIgnore = existsSync(ignored) ? readFileSync(ignored, 'utf8') : '';
+    if (!ignore().add(oldIgnore).ignores('.promptframe/local-previews/resources.json'))
+        writeFileSync(ignored, oldIgnore.replace(/\n?$/, '\n') + '.promptframe/\n');
+    writePreviewResourceSelection(root, { prop, ...(selectedFile ? { file: selectedFile } : { reference, sessionId }) });
+    const config = existsSync(join(root, 'vite.config.ts')) ? readFileSync(join(root, 'vite.config.ts'), 'utf8') : '';
+    printJson({ command: 'resource.set', status: 'selected', prop, source: selectedFile ? 'local_file' : 'platform_asset',
+        draftOnly: true, sourcePreviewPropsChanged: false, platformWrites: 0,
+        previewAdapter: config.includes('@promptframe/cli/preview') ? 'configured' : 'setup_required',
+        nextAction: 'Refresh the local preview. Existing custom Vite shells need promptFramePreviewResources().' });
+}
 async function devWorkspace(root, argv) {
     const studioOrigin = valueAfter(argv, '--studio-origin')
         ?? fail('Workspace dev requires --studio-origin <exact-origin>.', 'dev.workspace.origin_required', 2);
@@ -1685,6 +1744,7 @@ function buildVersionNotesHeaders(versionNotes) {
     return versionNotes ? { 'x-promptframe-version-notes': versionNotes } : {};
 }
 const POSITIONAL_VALUE_FLAGS = new Set([
+    '--prop', '--file', '--asset-ref',
     '--allowed-upload-target',
     '--auth-permissions',
     '--auth-roles',
@@ -1874,7 +1934,8 @@ async function loginWithDeviceCode(endpoint, argv) {
             contractVersion: CLI_AUTH_CONTRACT_VERSION,
             endpoint,
             clientName: `PromptFrame CLI on ${os.hostname()}`,
-            requestedScopes: DEFAULT_CLI_LOGIN_SCOPES,
+            requestedScopes: [...new Set([...(valuesAfter(argv, '--scope').length ? valuesAfter(argv, '--scope') : DEFAULT_CLI_LOGIN_SCOPES),
+                    ...(hasFlag(argv, '--with-assets') ? ['asset.read'] : [])])],
         }),
     }, 'login.device_start.failed');
     const deviceCode = requiredPayloadString(startPayload, 'deviceCode', 'login.device_start.invalid');
@@ -2015,6 +2076,7 @@ async function initProjectContext(argv) {
         projectId,
         projectNamespace: valueAfter(argv, '--project-namespace')
             ?? stringValue(project.projectNamespace)
+            ?? stringValue(project.namespace)
             ?? normalizeProjectNamespace(projectId),
         defaultUploadTarget: valueAfter(argv, '--target')
             ?? valueAfter(argv, '--upload-target')
@@ -3018,18 +3080,12 @@ function resolveBearerToken(endpoint, argv) {
         ?? process.env.PROMPTFRAME_CI_TOKEN
         ?? process.env.PROMPTFRAME_CLI_TOKEN
         ?? process.env.PROMPTFRAME_AUTH_TOKEN;
-    if (explicit)
-        return explicit;
-    const credential = asRecord(readConfig(argv).credential);
-    if (!credential)
-        return undefined;
-    if (normalizeEndpoint(stringValue(credential.endpoint) ?? '') !== normalizeEndpoint(endpoint))
-        return undefined;
-    const expiresAt = stringValue(credential.expiresAt);
-    if (expiresAt && Date.parse(expiresAt) <= Date.now()) {
-        fail('Stored PromptFrame CLI credential is expired. Run promptframe login again.', 'cli.auth.token_expired', 2);
+    try {
+        return cliBearerToken({ endpoint, explicit, configuration: readConfig(argv) });
+    }
+    catch {
+        return fail('Stored PromptFrame CLI credential is expired. Run promptframe login again.', 'cli.auth.token_expired', 2);
     }
-    return stringValue(credential.tokenSecret);
 }
 function describeAuthForEndpoint(endpoint, argv) {
     const credential = asRecord(readConfig(argv).credential);
@@ -3168,15 +3224,7 @@ function fileCredentialWarning() {
     };
 }
 function readConfig(argv) {
-    const path = resolveConfigPath(argv);
-    if (!existsSync(path))
-        return {};
-    try {
-        return JSON.parse(readFileSync(path, 'utf8'));
-    }
-    catch {
-        return {};
-    }
+    return readCliConfiguration(resolveConfigPath(argv));
 }
 function writeConfig(argv, config) {
     const path = resolveConfigPath(argv);
@@ -3315,6 +3363,15 @@ function validatePreviewProps(dir, manifest) {
     assertStaticSchemaResolved(schemaFacts, manifest.entry.propsSchemaPath);
     assertPreviewPropsMatchStaticSchema(manifest, preview, schemaFacts);
     assertStaticPropsHaveDescriptions(schemaFacts, manifest.entry.propsSchemaPath);
+    let references;
+    try {
+        references = collectPromptFrameResourceReferences({ type: 'object', properties: schemaFacts.properties }, preview.props ?? {});
+    }
+    catch {
+        fail('Public preview resource fields must use valid example paths.', 'component_standard.preview.resource_invalid');
+    }
+    if (references.some(row => row.source !== 'public'))
+        fail('Private resource selections belong in resource set drafts; public preview props must use package examples.', 'component_standard.preview.private_resource_reference');
 }
 function assertPreviewDurationMatchesManifest(preview, manifest) {
     const durationFrames = Number(preview.durationFrames);
@@ -3729,8 +3786,8 @@ function classifyPreviewShell(source) {
     }
     return 'custom_or_unknown';
 }
-function renderPromptFrameThinPreviewRoot() {
-    return `import { Player } from '@remotion/player';
+function renderPromptFrameThinPreviewRoot(localResources = false) {
+    const source = `import { Player } from '@remotion/player';
 import {
   PromptFramePreviewApp,
   resolvePromptFramePreviewLocale,
@@ -3799,6 +3856,17 @@ createRoot(root).render(
   </StrictMode>,
 );
 `;
+    if (!localResources)
+        return source;
+    return source
+        .replace("import { propsSchema, type ComponentProps } from './schema';", "import { propsSchema, type ComponentProps } from './schema';\nimport { promptFrameLocalPreview } from 'virtual:promptframe-local-preview';")
+        .replace('const initialPropsParse = propsSchema.safeParse(preview.props ?? {});', 'async function mountPreview() {\nconst localPreview = await promptFrameLocalPreview;\nconst initialPropsParse = propsSchema.safeParse(localPreview.props ?? preview.props ?? {});')
+        .replace('  <StrictMode>\n    <PromptFramePreviewApp', '  <StrictMode>\n    {localPreview.issues.length > 0 && <p role="alert" style={{ padding: 12 }}>\n      本地预览素材不可用，当前显示包内示例。请核对所选文件、作品与 CLI 素材读取授权后刷新。\n    </p>}\n    <PromptFramePreviewApp')
+        + '\n}\nvoid mountPreview();\n';
+}
+function hasResourcePreviewAdapter(dir) {
+    const path = join(dir, 'vite.config.ts');
+    return existsSync(path) && readFileSync(path, 'utf8').includes('@promptframe/cli/preview');
 }
 function assertPublicResourcesAccepted(report) {
     const firstError = report.diagnostics.find((item) => item.severity === 'error');
@@ -3962,13 +4030,43 @@ function decodeZipEntry(data, method) {
 }
 function collectPackageFiles(root) {
     const files = [];
-    function walk(dir) {
+    const manifest = parseComponentManifest(normalizeLegacyManifest(JSON.parse(readFileSync(join(root, 'manifest.json'), 'utf8'))));
+    const requiredPaths = new Set([
+        ...REQUIRED_COMPONENT_FILES,
+        manifest.entry.sourcePath,
+        manifest.entry.propsSchemaPath,
+    ]);
+    function walk(dir, inherited) {
+        const rules = [...inherited];
+        const ignorePath = join(dir, '.gitignore');
+        if (existsSync(ignorePath)) {
+            if (!lstatSync(ignorePath).isFile()) {
+                fail('.gitignore must be an ordinary file inside the component directory.', 'package.gitignore.invalid');
+            }
+            rules.push({ root: dir, matcher: ignore({ ignorecase: false }).add(readFileSync(ignorePath, 'utf8')) });
+        }
         for (const entry of readdirSync(dir, { withFileTypes: true })) {
             if (['node_modules', 'dist', '.git', '.component-packages', '.promptframe'].includes(entry.name))
                 continue;
             const full = join(dir, entry.name);
+            const name = relative(root, full).replace(/\\/g, '/');
+            let ignored = false;
+            for (const rule of rules) {
+                const result = rule.matcher.test(`${relative(rule.root, full).replace(/\\/g, '/')}${entry.isDirectory() ? '/' : ''}`);
+                if (result.ignored)
+                    ignored = true;
+                else if (result.unignored)
+                    ignored = false;
+            }
+            if (ignored) {
+                const containsRequiredPath = [...requiredPaths].some((requiredPath) => requiredPath === name || (entry.isDirectory() && requiredPath.startsWith(`${name}/`)));
+                if (containsRequiredPath || name === 'public' || name.startsWith('public/')) {
+                    fail(`.gitignore excludes required component content: ${name}. Remove that rule or explicitly include the required source/resource.`, 'package.required_file.ignored');
+                }
+                continue;
+            }
             if (entry.isDirectory()) {
-                walk(full);
+                walk(full, rules);
             }
             else if (entry.isFile()) {
                 if (entry.name === LOCKFILE_EVIDENCE_FILE_NAME)
@@ -3976,13 +4074,13 @@ function collectPackageFiles(root) {
                 if (isPackageManagerLockfile(entry.name))
                     continue;
                 files.push({
-                    name: relative(root, full).replace(/\\/g, '/'),
+                    name,
                     data: readFileSync(full),
                 });
             }
         }
     }
-    walk(root);
+    walk(root, []);
     const evidence = buildLockfileEvidenceFile(root);
     if (evidence)
         files.push(evidence);
@@ -4329,6 +4427,8 @@ Commands:
   sync <dir>                       Refresh PromptFrame-generated authoring shell files (--dry-run by default; use --apply)
   preview <dir>                    Validate and print local Remotion preview envelope
     --write-local-report           Write .promptframe/local-previews/preview-report.json
+  resource set <dir>               Select a private local preview resource (--prop /field, --file path OR --asset-ref ref --session-id id)
+  resource status|clear <dir>      Inspect or clear private preview selections; original files are retained
   dev <dir>                        Start a local preview or workspace checked-module connection
     --studio-origin <origin>        Required for a multi-component workspace
     --idle-timeout <minutes>        Workspace idle exit (default 30; 0 disables)
@@ -4345,6 +4445,7 @@ Commands:
   probe <buildId> --level <level>  Rerun component layout/security probe
   login --endpoint <url>             Start browser login code flow and store a CLI token
     --token <token>                  Verify and store an already issued CLI/CI token
+    --with-assets                   Explicitly request asset.read in the normal browser authorization
   whoami                            Show the current PromptFrame CLI identity
   logout                            Revoke the current CLI token and clear local config
   discovery                         Fetch platform endpoint and self-service capabilities