@scalemule/news-publication 0.0.79 → 0.0.81

package/README.md

@@ -338,6 +338,79 @@ The platform contract and a complete example live in
 `docs/news-platform/ARTICLE-WORKFLOW-V1.md` in the ScaleMule meta-repo.
 Do not use direct SQL, S3 paths, base64 bodies or invented media readiness.
 
+### Edit article prose, cards and citations
+
+```sh
+npx --yes --package @scalemule/news-publication@0.0.81 scalemule-article edit \
+  --url "$ARTICLE_URL" --patch ./approved-edit.json --operation-key correction-v1
+```
+
+The patch may contain title, subtitle, content_markdown, excerpt, section,
+community, format, layout, cards and citations. It preserves omitted fields and
+media and saves one immutable revision. Default: save for review. Add
+`--release` only to request release through the existing policy; the command
+never issues APPROVE or downgrades review. On a legacy article, explicitly choose
+`--enable-review-policy` only as a legitimate editorial onboarding decision.
+Scheduled legacy articles stop before onboarding. Normal API-key/member grants
+remain authoritative; the deployed server must advertise
+`versioned_editorial_fields`.
+
+The 10-second default deadline bounds the operation; `--timeout-ms` may raise it
+to at most 120 seconds. Keep the same patch/key and private checkpoint
+(`--state` or `~/.scalemule/newsroom/operations`) on retries. The checkpoint
+contains the submitted document and private provenance: never publish it.
+Unknown save/release responses reconcile against the original revision; another
+current revision stops rather than being overwritten. Completed replay and no-op
+edits add no revision. `RELEASE_HELD`/exit 2 preserves the saved revision while
+review is pending. With `--url --release`, success requires the rendered
+headline, prose and actual card components; public visibility pending is also
+exit 2. A saved revision and a rendered published correction are separate states.
+
+Use the same client method, `client.editArticle`, for a caller-supplied durable
+checkpoint store. This is local resumability over the existing server save
+receipt, not a distributed transaction covering entities, syndication, media
+commissioning or human review. The notices-only `/editorial` endpoint is not
+an article-body/card editor. Routine content corrections require no backend PR.
+
+### Replace a published article photo from a local file
+
+```sh
+npx --yes --package @scalemule/news-publication@0.0.80 scalemule-article replace-photo \
+  --url "$ARTICLE_URL" --file ./venue-exterior.jpg \
+  --metadata ./photo.json --operation-key venue-exterior-v1
+```
+
+Use the normal authorized member's `SCALEMULE_API_KEY` and
+`SCALEMULE_ACCESS_TOKEN`. The caller needs developer-level asset access and
+publication approval rights. Supply caption, credit, factual alt, confirmed rights,
+explicit `aiGenerated` and `label` (null for an ordinary photo) in `photo.json`.
+The URL resolves the authorized publication and article; no UUID search or
+publication build is needed. This does not find a photo or establish rights.
+
+`uploadAndReplacePublishedCover` implements the same operation for applications.
+It transfers bytes through managed Storage, preserves private capture evidence,
+waits for a clean scan, registers Photo, prepares the publication's lead,
+thumbnail and social renditions, reads measured delivery receipts and performs
+one article-version-fenced media write. It verifies unchanged text/audio and,
+when given `--url`, checks the selected lead and social URLs in the public HTML.
+It requires the deployed content-first document and member Photo endpoints.
+
+A private atomic checkpoint lives under `~/.scalemule/newsroom/operations`
+(or `--state PATH`). Keep it: it contains a temporary upload credential until
+completion. Reuse the same file, metadata and operation key after interruption.
+A completed replay verifies the same attachment without uploading or writing
+again. A concurrent article change stops instead of overwriting the editor.
+The default per-run deadline is 30 seconds, adjustable with `--timeout-ms` up to
+120 seconds; timeouts name the blocked stage and preserve progress. Exit 2 means
+API attachment succeeded but public HTML visibility is still pending. A timeout
+is not a success receipt. This is local resumability, not a distributed
+exactly-once service or a guaranteed image-processing SLA.
+
+This published-cover convenience lane stops before upload for collaboration
+articles. Their immutable revision, approval and release gates still apply.
+Animated GIF/APNG/WebP and videos use the Video workflow; this lane accepts
+still JPEG, PNG and WebP up to 25 MiB.
+
 ### Replace an existing, prepared cover
 
 For a legacy published article and an already public, scanned Photo asset,

package/bin/scalemule-article.mjs

@@ -1,16 +1,41 @@
 #!/usr/bin/env node
-import { readFile } from 'node:fs/promises';
+import { readFile, mkdir, writeFile, rename, open, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, basename } from 'node:path';
+import { createHash } from 'node:crypto';
 import { parseArgs } from 'node:util';
-import { PublicationArticleClient } from '../dist/article-workflow-client.js';
+import { PublicationArticleClient, articlePhotoHtmlMatches,articleEditHtmlMatches } from '../dist/article-workflow-client.js';
 
 const help = `Usage:
   scalemule-article inspect --publication ID --article ID
   scalemule-article replace-cover --publication ID --article ID --file-id ID --expected-version N --metadata photo.json
+  scalemule-article replace-photo --url ARTICLE_URL --file PHOTO --metadata photo.json --operation-key KEY
+  scalemule-article edit --url ARTICLE_URL --patch edit.json --operation-key KEY [--release]
 
 Credentials: SCALEMULE_API_KEY and SCALEMULE_ACCESS_TOKEN (normal authorized member).
 Platform admins may use their normal access token with --application-id ID.
 Optional --api-url URL defaults to https://api.scalemule.com.
 
+edit saves prose, excerpt, cards and citations in one immutable revision.
+Unspecified fields and media are retained. Default: save for review.
+--release explicitly requests release under the existing policy; it never issues
+APPROVE or changes a policy. Legacy onboarding requires an explicit
+--enable-review-policy value. Scheduled legacy articles stop before onboarding.
+Use --expected-generation when coordinating an edit with another editor.
+Default edit deadline: 10000 ms. Reuse the same patch/key/checkpoint on retry.
+RELEASE_HELD means the revision is saved and existing review gates remain.
+
+replace-photo accepts a local file and uses normal member/API-key credentials.
+It requires developer-level asset access and publication approval rights.
+It resolves the publication from its authorized API inventory, saves a private
+upload checkpoint, resumes the same multipart part, waits for scan and measured
+publication renditions, then attaches with the original article version fence.
+It verifies article invariants and, with --url, the public page. The default
+deadline is 30 seconds per run; a failure names its stage and preserves progress.
+Reuse the same --operation-key, metadata and file when resuming. Optional
+--state PATH and --timeout-ms N (maximum 120000). Review-managed articles stop
+before uploading and require their existing exact-revision editorial workflow.
+
 replace-cover selects an already public, scanned Photo asset. It reads measured
 hero and social renditions, preserves the article text, and changes media with
 the supplied version fence. It never uploads raw bytes, republishes the story,
@@ -29,13 +54,35 @@ that every website/CDN cache already displays the new image.
 try {
   const { values, positionals } = parseArgs({
     allowPositionals: true, strict: true,
-    options: Object.fromEntries(['publication', 'article', 'file-id', 'expected-version', 'metadata', 'application-id', 'api-url'].map(k => [k, { type: 'string' }]).concat([['help', { type: 'boolean' }]])),
+    options: Object.fromEntries(['publication', 'article', 'file-id', 'expected-version', 'metadata', 'application-id', 'api-url', 'url', 'file', 'operation-key', 'state', 'timeout-ms','patch','expected-generation','enable-review-policy'].map(k => [k, { type: 'string' }]).concat([['help', { type: 'boolean' }],['release',{type:'boolean'}]])),
   });
   if (values.help || !positionals.length) {
     console.log(help);
   } else {
     const [command, ...extra] = positionals;
-    if (extra.length || !['inspect', 'replace-cover'].includes(command)) throw Error('Use inspect or replace-cover; see --help');
+    const commandStarted = performance.now();
+    const budget = Number(values['timeout-ms'] ?? (command==='edit'?10000:30000));
+    if (!Number.isFinite(budget) || budget < 100 || budget > 120000) throw Error('--timeout-ms must be between 100 and 120000');
+    const remaining = () => { const ms = Math.floor(budget - (performance.now()-commandStarted)); if (ms < 1) throw Error('Operation deadline reached; resume the same operation'); return ms; };
+    if (extra.length || !['inspect', 'replace-cover', 'replace-photo','edit'].includes(command)) throw Error('Use inspect, edit, replace-cover or replace-photo; see --help');
+    if (values.url) {
+      if (!process.env.SCALEMULE_API_KEY || !process.env.SCALEMULE_ACCESS_TOKEN || values['application-id']) throw Error('URL resolution requires normal publication member/API-key credentials');
+      const url = new URL(values.url);
+      if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) throw Error('Use the public HTTPS article URL, without a private review key');
+      const api = values['api-url'] ?? 'https://api.scalemule.com';
+      const apiOrigin = new URL(api); if (apiOrigin.protocol !== 'https:' || apiOrigin.username || apiOrigin.password) throw Error('Use an HTTPS platform API endpoint');
+      const headers = { 'x-api-key': process.env.SCALEMULE_API_KEY, authorization: 'Bearer '+process.env.SCALEMULE_ACCESS_TOKEN };
+      const get = async route => { const r = await fetch(api.replace(/\/$/,'')+route,{headers,redirect:'error',cache:'no-store',signal:AbortSignal.timeout(Math.min(10000,remaining()))}); const v = await r.json(); if (!r.ok || !v.success) throw Error(`Article resolution HTTP ${r.status}`); return v.data; };
+      const pubs = await get('/v1/blog/publications');
+      const pub = pubs.items?.find(p=>new URL(p.canonical_url).origin===url.origin);
+      if (!pub) throw Error('The caller has no publication grant for that article origin');
+      const match = /^\/news\/([^/]+)\/?$/.exec(url.pathname);
+      if (!match) throw Error('Use the publication article slug URL');
+      const resolved = await get(`/v1/blog/publications/${encodeURIComponent(pub.id)}/article-content/${encodeURIComponent(decodeURIComponent(match[1]))}`);
+      if (!resolved.article?.id) throw Error('No published article at this URL');
+      if ((values.publication && values.publication !== pub.id) || (values.article && values.article !== resolved.article.id)) throw Error('Article URL and supplied IDs disagree');
+      values.publication = pub.id; values.article = resolved.article.id;
+    }
     for (const key of ['publication', 'article']) if (!values[key]) throw Error(`Missing --${key}`);
     if (!process.env.SCALEMULE_ACCESS_TOKEN) throw Error('SCALEMULE_ACCESS_TOKEN is required; use normal member or platform admin authorization');
     if (!values['application-id'] && !process.env.SCALEMULE_API_KEY) throw Error('Member calls also require SCALEMULE_API_KEY');
@@ -62,6 +109,114 @@ try {
         capabilities: options.capabilities, narration: processing.narration,
         assets: processing.assets, collaboration, elapsed_ms: Math.round(performance.now() - started),
       }, null, 2));
+    } else if (command==='edit') {
+      for(const key of ['patch','operation-key'])if(!values[key])throw Error('Missing --'+key);
+      const patch=JSON.parse(await readFile(values.patch,'utf8'));
+      const key=createHash('sha256').update(JSON.stringify(['edit',values['api-url']??'https://api.scalemule.com',values.publication,values.article,values['operation-key']])).digest('hex');
+      const statePath=values.state??join(homedir(),'.scalemule','newsroom','operations',key+'.json');
+      await mkdir(dirname(statePath),{recursive:true,mode:0o700});
+      const lockPath=statePath+'.lock';let lock;
+      try{lock=await open(lockPath,'wx',0o600);}catch(error){
+        if(error.code!=='EEXIST')throw error;
+        const pid=Number(await readFile(lockPath,'utf8'));if(!Number.isSafeInteger(pid)||pid<1)throw Error('Invalid operation lock; inspect '+lockPath);
+        let alive=true;try{process.kill(pid,0);}catch(e){if(e.code==='ESRCH')alive=false;else throw e;}
+        if(alive)throw Error('This edit operation is already running');
+        await unlink(lockPath);lock=await open(lockPath,'wx',0o600);
+      }
+      await lock.writeFile(String(process.pid));await lock.close();
+      try{
+        let checkpoint;try{checkpoint=JSON.parse(await readFile(statePath,'utf8'));}catch(error){if(error.code!=='ENOENT')throw error;}
+        const result=await client.editArticle({articleId:values.article,operationKey:values['operation-key'],patch,
+          expectedGeneration:values['expected-generation']===undefined?undefined:Number(values['expected-generation']),
+          enableReviewPolicy:values['enable-review-policy'],release:values.release,checkpoint,timeoutMs:remaining(),
+          saveCheckpoint:async state=>{const temp=statePath+'.'+process.pid+'.tmp';await writeFile(temp,JSON.stringify(state),{mode:0o600});await rename(temp,statePath);checkpoint=state;},
+        });
+        if(values.url&&values.release&&['published','already_published'].includes(result.state)){
+          let verified=false,reason;
+          try{
+            const snapshot=await client.publicArticle(checkpoint.sourceIdentity.slug,AbortSignal.timeout(remaining()));
+            const article=snapshot.article;
+            if(!article||!article.content_html||article.id!==values.article)throw Error('Published reader snapshot is missing');
+            while(!verified){
+              const response=await fetch(values.url,{redirect:'error',cache:'no-store',signal:AbortSignal.timeout(Math.min(5000,remaining()))});
+              const html=await response.text();
+              verified=response.ok&&articleEditHtmlMatches(html,{title:article.title,content_html:article.content_html,card_titles:(article.metadata?.cards??[]).map(c=>c.title)});
+              if(!verified)await new Promise(r=>setTimeout(r,Math.min(300,remaining())));
+            }
+          }catch(error){reason=error.message;}
+          if(!verified){console.error(JSON.stringify({...result,state:'published_public_verification_pending',stage:'public_page',message:'The exact revision is published; rendered prose/cards remain unverified. Resume the same edit.',reason}));process.exitCode=2;}
+          else console.log(JSON.stringify({...result,public_page_verified:true,total_elapsed_ms:Math.round(performance.now()-commandStarted)},null,2));
+        }else{
+        console.log(JSON.stringify({...result,total_elapsed_ms:Math.round(performance.now()-commandStarted)},null,2));
+        }
+      }finally{await unlink(lockPath);}
+    } else if (command === 'replace-photo') {
+      for (const key of ['file','metadata','operation-key']) if (!values[key]) throw Error(`Missing --${key}`);
+      if (values['application-id']) throw Error('Local-photo intake uses normal publication member credentials');
+      const metadata = JSON.parse(await readFile(values.metadata,'utf8'));
+      for (const key of ['caption','credit','alt']) if (typeof metadata[key] !== 'string') throw Error(`photo.json requires a string ${key}`);
+      const key = createHash('sha256').update(JSON.stringify([values['api-url']??'https://api.scalemule.com',values.publication,values.article,values['operation-key']])).digest('hex');
+      const statePath = values.state ?? join(homedir(),'.scalemule','newsroom','operations',key+'.json');
+      await mkdir(dirname(statePath),{recursive:true,mode:0o700});
+      const lockPath = statePath+'.lock';
+      let lock;
+      try { lock = await open(lockPath,'wx',0o600); }
+      catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        const pid = Number(await readFile(lockPath,'utf8'));
+        if (!Number.isSafeInteger(pid) || pid < 1) throw Error('Operation lock is invalid; inspect '+lockPath);
+        let alive = true; try { process.kill(pid,0); } catch (e) { if (e.code === 'ESRCH') alive = false; else throw e; }
+        if (alive) throw Error('This operation is already running; use its existing result');
+        await unlink(lockPath); lock = await open(lockPath,'wx',0o600);
+      }
+      await lock.writeFile(String(process.pid)); await lock.close();
+      try {
+        let checkpoint;
+        try { checkpoint = JSON.parse(await readFile(statePath,'utf8')); } catch(error) { if (error.code !== 'ENOENT') throw error; }
+        const expectedVersion = Number(values['expected-version'] ?? checkpoint?.expectedVersion ?? (await client.processing(values.article,AbortSignal.timeout(remaining()))).version);
+        const bytes = await readFile(values.file);
+        const saveCheckpoint = async state => { const temp = statePath+'.'+process.pid+'.tmp'; await writeFile(temp,JSON.stringify(state),{mode:0o600}); await rename(temp,statePath); checkpoint = state; };
+        const result = await client.uploadAndReplacePublishedCover({
+          articleId:values.article, expectedVersion, operationKey:values['operation-key'],file:new Blob([bytes]),filename:basename(values.file),
+          caption:metadata.caption,credit:metadata.credit,alt:metadata.alt,rightsConfirmed:metadata.rightsConfirmed,aiGenerated:metadata.aiGenerated,label:metadata.label,focalPoint:metadata.focalPoint,
+          checkpoint,saveCheckpoint,timeoutMs:remaining(),
+          onProgress:event=>console.error(JSON.stringify(event)),
+        });
+        if (values.url) {
+          let visible = false;
+          let failure;
+          try {
+            const images = [checkpoint?.payload?.cover_image_url, checkpoint?.payload?.og_image_url];
+            const leads = new Set([images[0],...(checkpoint?.payload?.cover_image?.variants??[]).map(v=>v.url)].filter(Boolean));
+            while (!visible) {
+              const response = await fetch(values.url,{redirect:'error',cache:'no-store',signal:AbortSignal.timeout(Math.min(10000,remaining()))});
+              const html = await response.text();
+              visible = response.ok && images.every(Boolean) && articlePhotoHtmlMatches(html,[...leads],images[1]);
+              if (!visible) {
+                // Sites may select another measured responsive rendition of the
+                // same Photo. Read that evidence; never infer a CDN path or ID.
+                await Promise.all(['image/webp','image/jpeg','image/avif'].map(async accept=>{
+                  const api=(values['api-url']??'https://api.scalemule.com').replace(/\/$/,'');
+                  const r=await fetch(api+'/v1/photos/public/'+encodeURIComponent(result.file_id)+'/manifest?preset=hero',{headers:{accept},redirect:'error',signal:AbortSignal.timeout(Math.min(5000,remaining()))});
+                  const value=await r.json();
+                  if(!r.ok || !value.success || value.data?.file_id!==result.file_id) return;
+                  for(const v of Object.values(value.data.variant_metadata??{})) {
+                    if(!Number.isInteger(v.width)||v.width<1||!Number.isInteger(v.height)||v.height<1) continue;
+                    const u=new URL(v.url);
+                    if(u.protocol==='https:'&&!u.username&&!u.password&&!u.search&&!u.hash) leads.add(v.url);
+                  }
+                }));
+                visible = response.ok && images.every(Boolean) && articlePhotoHtmlMatches(html,[...leads],images[1]);
+              }
+              if (!visible) await new Promise(resolve=>setTimeout(resolve,Math.min(500,remaining())));
+            }
+          } catch(error) { failure = error.message; }
+          if (!visible) {
+            console.error(JSON.stringify({...result,state:'attached_public_verification_pending',stage:'public_page',message:'The API attachment is verified; public HTML visibility remains pending. Resume this same operation.',reason:failure}));
+            process.exitCode = 2;
+          } else console.log(JSON.stringify({...result,public_page_verified:true,total_elapsed_ms:Math.round(performance.now()-commandStarted)},null,2));
+        } else console.log(JSON.stringify(result,null,2));
+      } finally { await unlink(lockPath); }
     } else {
       for (const key of ['file-id', 'expected-version', 'metadata']) if (!values[key]) throw Error(`Missing --${key}`);
       const metadata = JSON.parse(await readFile(values.metadata, 'utf8'));
@@ -78,6 +233,6 @@ try {
     }
   }
 } catch (error) {
-  console.error(JSON.stringify({ error: error.message, status: error.status }));
-  process.exitCode = 1;
+  console.error(JSON.stringify({ error: error.message, status: error.status, code:error.code, stage:error.stage, file_id:error.fileId,revision_id:error.revisionId }));
+  process.exitCode = error.code==='RELEASE_HELD'?2:1;
 }

package/dist/{article-presentation-BrNCcF-5.d.cts → article-presentation-0d1FiDgA.d.cts}

@@ -18,4 +18,4 @@ declare function articlePresentation(value?: ArticlePresentation | null): Articl
 declare function articleHeroRatio(layout: ArticleLayout): number;
 declare function articleFormatLabel(format?: ArticleFormat | null): string | undefined;
 
-export { type ArticleFormat as A, type ArticleLayout as a, type ArticlePresentation as b, articleFormatLabel as c, articleHeroRatio as d, articlePresentation as e };
+export { type ArticleFormat as A, type ArticlePresentation as a, type ArticleLayout as b, articleFormatLabel as c, articleHeroRatio as d, articlePresentation as e };

package/dist/{article-presentation-BrNCcF-5.d.ts → article-presentation-0d1FiDgA.d.ts}

@@ -18,4 +18,4 @@ declare function articlePresentation(value?: ArticlePresentation | null): Articl
 declare function articleHeroRatio(layout: ArticleLayout): number;
 declare function articleFormatLabel(format?: ArticleFormat | null): string | undefined;
 
-export { type ArticleFormat as A, type ArticleLayout as a, type ArticlePresentation as b, articleFormatLabel as c, articleHeroRatio as d, articlePresentation as e };
+export { type ArticleFormat as A, type ArticlePresentation as a, type ArticleLayout as b, articleFormatLabel as c, articleHeroRatio as d, articlePresentation as e };